Skip to main content
An agent is the hosted unit behind a stable URL - what an agent project becomes when you deploy it. The link between your local project and its hosted agent is the local karta.toml: per-agent commands resolve an explicit --agent or slug first, then the agent in this folder, the repo’s sole local agent, and finally the legacy KARTA_PROJECT alias. Deployment itself is folder-scoped even when several agents share one git repository.

​
Deploy

karta deploy ships one agent project using the deploy_method in its local karta.toml. On first git deploy it provisions the hosted source and wires the repository’s karta remote; folder deploy uploads only the selected folder. For low-level git use, target the agent’s reserved deploy ref explicitly:
Plain git push karta main is a compatibility convenience for a repository with one enabled agent. It never fans out a multi-agent repository. See Releases & rollback for the deploy flow in depth, including plain folders and CI.

​
Inspect

​
Roll back

Rollback flips the active release pointer back - instant, and the agent URL is unaffected. In-flight sessions finish on the release they started on. Use karta rollback when you mean “revert production.” Use karta agent activate when you want to activate a specific existing production release as an explicit operation.

​
Agent controls

​
Logs

​
Open

Run it inside the agent project directory and Karta reads the local karta.toml; elsewhere, pass --agent <slug> or set KARTA_PROJECT in CI.

​
Clone a karta’s workspace

Each karta is a durable computer, and its files persist across sessions. With workspace access enabled, an org admin can clone that workspace read-only over git to see what the agent has accumulated for a karta. Turn it on in the console first: on the agent’s Settings tab, enable Workspace access, or run:
It’s a sensitive change, so the product records the change and the console may ask you to re-verify your identity. The agent page then shows a ready-to-run clone command for each karta:
karta login installs a git credential helper that authenticates the clone for you - no token to copy or paste. Access is read-only: clone and pull work, push does not.

​
Where sessions fit

For local Karta parity, use karta dev: it runs your agent behind the same session API on your machine, with hot reload and a REPL - see the CLI overview. In production, sessions are driven through the session API by your frontend or the chat widget; the hosted chat page (karta open) is the quickest way to talk to a live deploy.