Codity Agents
Codity Agents run tasks on a machine you choose and report their activity to the dashboard. Use them to investigate logs, work on a checkout, or keep an interactive coding session under permissions your team controls.
Where an agent runs
Create an agent in the dashboard, then run its generated install command on your laptop, development server, or another machine you manage. Clicking Deploy agent creates the configuration and install command; you still need to execute that command on the target machine.
The machine needs Node.js 18 or newer, access to Codity's agent service and downloads, and access to the selected model provider. Choose Linux (bash) or macOS (zsh) to match the target. Windows users should run the Linux flow inside WSL.
An agent configuration can have several runs. A run represents one execution on a machine, with its own history, status, usage and permission requests.
Choose a run mode
| Mode | Use it when | Task required? |
|---|---|---|
| Headless | You want the agent to execute a task unattended and report back. | Yes. |
| Interactive (TUI) | You want to talk to the agent in your terminal. | No. Enter a task after it starts, or provide an opening task in the form. |
The name is generated for you and can be changed. A name, model and provider API key are required in the dashboard. The Agents tab and deployment form do not require a Premium subscription. Editing shared policies requires an account administrator. Public API access has its own authentication and subscription requirements.
Model access and billing
Choose a provider and model, and supply that provider's API key. Model usage is billed to your provider account. The dashboard encrypts the supplied key before storage and does not return it later. A Codity API key authenticates API requests; it is separate from the model provider key.
The agent page shows reported input/output tokens, spend, runs and activity. Use your model provider's billing page as the source for your invoice.
Permissions and shared policies
Grant paths, command patterns and fetch URLs explicitly. Refuse rejects unlisted actions; Ask me sends an approval request and waits for a decision. An explicit deny remains denied in either mode.
Organization policies apply to every agent in that organization. A selected team's policy also applies. Shared allows supply defaults; shared denies always apply and cannot be overridden by an agent rule or an approval. Policy changes apply on the next run or resume.
These controls govern the agent's tools. If you grant a command that can execute arbitrary code, that command can access resources using the machine's normal permissions. Use a suitably restricted machine or container when you also need operating system isolation. See Permissions and YAML policies.
Pause and resume
Enable recovery when creating an agent to save encrypted conversation and tool checkpoints centrally. After a checkpoint exists, press Ctrl+C to pause. From the same working folder, continue with:
codity-agent resume --last
Recovery restores the saved conversation, not a running process or a backup of the machine's files. Interrupted actions require review before continuing. See Session recovery.
