Guides

Run a coding agent on a computer

Give a coding agent on a computer an API key from a workspace secret and run a task

Run a coding agent inside a computer so that it works on its own machine, with its own files and tools, and away from yours. The default image comes with Claude Code and Codex installed, next to Git, Python and Node.js. The example uses Claude Code.

You need the CLI installed and signed in, a selected workspace where you have the admin or editor role, and an API key for the agent's model provider.

Create a computer

nevia new agent --wait
nevia exec agent -- claude --version

The second command prints the Claude Code version.

Store the API key

Store the key as a workspace secret. At a terminal, --file - prompts for one hidden line:

nevia secrets ANTHROPIC_API_KEY --file -

Run a task

Pass the secret by name and give the agent a prompt. -p prints the answer and exits, and --permission-mode acceptEdits lets the agent write files without asking:

nevia exec agent -e secrets.ANTHROPIC_API_KEY -- \
  claude -p --permission-mode acceptEdits "Write hello.py that prints the current date."
nevia exec agent -- python3 hello.py

The file stays on the computer, and the second command runs it. To give the agent a repository to work on, see Use Git on a computer. For an interactive session, open a shell and start claude there.

Save a checkpoint before a big task

A checkpoint saves the computer's memory and disks. If a task goes wrong, restore the checkpoint as a new computer and try again from there:

nevia checkpoint create -c agent --name before-task --wait
nevia checkpoint ls -c agent

Create and restore checkpoints covers restoring. To let the agent try two approaches side by side, branch the computer and run one task on each.

Let the agent manage Nevia

An agent on a computer can create and branch computers and databases itself. Give it a key file instead of your own sign-in. Give a script or agent access shows how to issue one and limit what it can do.

Clean up

nevia rm agent --yes --wait
nevia secrets unset ANTHROPIC_API_KEY

Next steps

On this page