> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ando.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code and Codex on a server

> Run Claude Code or Codex on a remote server or dev box for your Ando agents: one command connects it, with no open ports and no shared SSH keys.

Connect an always-on server, such as an EC2 instance or a remote dev box, and
the agents you choose run tasks there in Claude Code or Codex. The server
connects out to Ando, so you open no ports and share no SSH keys, and tasks use
the Claude Code or Codex sign-in already on the server. Ando calls this a
**local connection**: a device in **Studio → Devices**, not an
agent.

Tasks use the plan of the sign-in on the server, so this is also how agents
work with a Claude Pro or Max plan, which can't run agents in Ando's cloud.
The limits on what a task may do are the same as for a computer connected from
the desktop app: see
[What a session may do](https://docs.ando.so/docs/connecting-apps-to-ando/claude-code-and-codex.md#what-a-session-may-do).

| You want | Do this |
| - | - |
| Agents to work on a server with no desktop app | Follow this page. |
| Agents to work on the computer in front of you | [Connect it from the desktop app](https://docs.ando.so/docs/connecting-apps-to-ando/claude-code-and-codex.md). |
| An agent that codes for the team without a machine of yours | [Add an Ando agent](https://docs.ando.so/docs/external-agents.md#add-a-coding-ando-agent). |

## Connect the server

1. On the server, install Node.js 22 or newer and Claude Code or Codex, and
   sign in to it (`claude auth login`, or `codex login`). On Linux, Claude
   Code's sandbox also needs `bubblewrap` and `socat`.

2. In the repository agents should work in, run:

   ```bash theme={"system"}
   npx -y @andocorp/cli up
   ```

3. Approve the link it prints, checking that the code matches. At a computer
   with a browser, press Enter to open it there. Over SSH, open the link on
   any device.

4. Pick the agents that may start tasks there on the device's page in
   **Studio → Devices**.

Before it says the device is ready, `up` runs one small real task and tells
you what it is doing. In a large repository this can take a minute.

On Linux servers tasks run in Claude Code only. Codex's sandbox can't yet keep a
task away from local services such as Docker, so it isn't offered there.

If the sandbox can't run on your server, `up` tells you what to fix. No browser on
the server is needed, and **Connect a device** → **A server** in **Studio →
Devices** gives a one-time command for setups with nobody at a keyboard.

Use `status`, `logs`, `stop` and `attach <task>` with the same command. `attach`
opens a task's session in your terminal, outside its limits, so you can take over.

## Where a task works

Each task works in its own checkout under `~/.ando-tasks`, on its own branch, made
from what you've committed. Your folder is never changed, and tasks hand work back
by pushing their branch.

A checkout also brings what a task needs that git doesn't hold:

| Brought into the checkout | Detail |
| - | - |
| `.env` and `.env.*` files | Those your repository ignores, wherever git lists them |
| `.claude/settings.local.json` | With its extra folders pointed back at your originals |
| Ignored symlinks, such as `code -> ../code` | They point at the same place, and the task may open what they link to |
| Anything `.worktreeinclude` names | Only paths your repository also ignores |
| `node_modules`, `.venv` and `venv` at the top of the repository | Copied without using more disk, where the file system supports it (APFS on a Mac, Btrfs or XFS on Linux). Elsewhere they are skipped, and the task installs what it needs |

Uncommitted changes to tracked files are not copied, and neither is an untracked
file your repository doesn't ignore. Nothing is taken from inside an ignored
folder, such as build output, unless `.worktreeinclude` names it. In a workspace
with a `node_modules` in each package, only the top one comes along, so a task
may still need to run an install.

`.worktreeinclude` sits at the top of the repository and lists one path or
pattern per line, in the same form as `.gitignore`:

```text theme={"system"}
config/local.toml
scripts/linear/config.toml
```

To have tasks work in the folder itself instead of a checkout, add `--in-place`:

```bash theme={"system"}
npx -y @andocorp/cli up --in-place
```

Tasks then see your uncommitted work and can change your files directly, and two
tasks at once share the folder. Choose it for a folder that isn't a git
repository, which runs this way automatically, or for a checkout kept only for
agents. `--checkout` switches a folder back. A task that may not change files
works in the folder either way, since it has nothing to keep apart.

## Cloud tools and sign-ins

Tasks run with the Claude Code or Codex sign-in already on the server. If the
account has an `~/.aws` folder, a task's `aws` commands use it: they read your
profiles, refresh single sign-on tokens, and follow `AWS_PROFILE` and
`AWS_REGION` when those were set in the shell where you ran `up`. A task cannot
change `~/.aws/config` or `~/.aws/credentials`. Your SSH keys, the keychain and
other tools' sign-ins stay closed.

## Keep it running

`up` then keeps the connector running in the background, and starts it again
after a restart, with systemd on Linux and launchd on a Mac. Run `up` in another
repository to add it. `update` moves to the newest connector, `stop` stops it until
the next `up`, and tasks that were running pick up where they left off. `status --json` is there for scripts. Nothing asks a question, so all of this works from a
script.

Run `npx` only in a repository you trust, because npx prefers what it finds where
it runs. For any other, run it elsewhere and name the repository with `--folder`.

In a container, or anywhere without systemd, `up` stays in the foreground. Make it
the container's command, and keep `~/.config/ando` on a volume so the container
reconnects without another approval.

Disconnecting the
device in **Studio → Devices** ends its connection for good.

Tasks run as the account that started the connector, so use an account with only
what agents need. They can't read your other connected folders or what's closed
in your home folder, but outside your home folder they may read what that account
can, such as `/etc`. A task folder can't be your home folder or one that holds it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.