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

# anona-compute CLI

> Sign in, manage sandboxes, run commands, SSH, live view and an MCP server for agents.

`anona-compute` is one static binary for Linux, macOS and Windows (amd64 and arm64). It is called `anona-compute` because `anona` is the Anona Memory CLI; the two have separate sign-ins and settings.

## Install

```bash install_cli.sh
npm install -g @anona-labs/anona-compute   # needs Node.js; installs the native binary for your platform
anona-compute version
```

The npm package is a small launcher that runs the native binary for your platform.

Without Node.js, use either of these instead:

* **Download the binary** from the [releases page](https://github.com/anonalabs/anona-compute-sdk/releases) (releases tagged `cli-v<version>`). Each platform has an archive holding the single `anona-compute` binary: `.tar.gz` for Linux and macOS, `.zip` for Windows. `SHA256SUMS` lists their checksums. Unpack it and put `anona-compute` on your `PATH`:

  ```text
  sha256sum -c SHA256SUMS --ignore-missing         # macOS: shasum -a 256 -c SHA256SUMS --ignore-missing
  tar -xzf anona-compute_<version>_linux_amd64.tar.gz
  sudo install anona-compute /usr/local/bin/
  ```

* **Build it with Go** 1.26 or newer. The source is in the public [anona-compute-sdk](https://github.com/anonalabs/anona-compute-sdk) repository, under `cli/`:

  ```text
  go install github.com/anonalabs/anona-compute-sdk/cli/cmd/anona-compute@latest
  ```

  The binary goes to `$(go env GOPATH)/bin`; make sure that is on your `PATH`.

## Sign in

```text
anona-compute login                 # browser sign-in (device code); --no-browser prints the URL only
anona-compute whoami                # user, organization, role
anona-compute logout                # revokes this machine's session on the dashboard
```

Or use an API key, which wins over a browser sign-in:

```bash cli_key.sh
printenv ANONA_API_KEY | anona-compute login --with-api-key   # saves it in the profile
anona-compute whoami
anona-compute list                                           # reads ANONA_API_KEY; or pass --api-key
```

## A tour

```bash cli_tour.sh
SANDBOX_ID=$(anona-compute create -t base --timeout 30m --json | jq -r .sandbox_id)
anona-compute list
anona-compute info "$SANDBOX_ID"
anona-compute exec "$SANDBOX_ID" -- 'echo hello > /tmp/x && cat /tmp/x'
anona-compute timeout "$SANDBOX_ID" 1h
anona-compute pause "$SANDBOX_ID"
anona-compute resume "$SANDBOX_ID"
anona-compute view "$SANDBOX_ID" --mode terminal --control
anona-compute delete "$SANDBOX_ID"
```

| Task | Commands |
| - | - |
| Lifecycle | [`create`](/docs/cli/reference/create), [`list`](/docs/cli/reference/list), [`info`](/docs/cli/reference/info), [`pause`](/docs/cli/reference/pause), [`resume`](/docs/cli/reference/resume), [`timeout`](/docs/cli/reference/timeout), [`fork`](/docs/cli/reference/fork), [`delete`](/docs/cli/reference/delete) |
| Run things | [`exec`](/docs/cli/reference/exec), [`run`](/docs/cli/reference/run), [`output`](/docs/cli/reference/output), [`ps`](/docs/cli/reference/ps), [`connect`](/docs/cli/reference/connect), [`logs`](/docs/cli/reference/logs) |
| Access | [`ssh`](/docs/cli/reference/ssh), [`scp`](/docs/cli/reference/scp), [`view`](/docs/cli/reference/view), [`desktop`](/docs/cli/reference/desktop), [`preview`](/docs/cli/reference/preview) |
| Agents | [`mcp`](/docs/cli/reference/mcp) |
| Credentials and idle pause | [`vault`](/docs/cli/reference/vault), [`idle-pause`](/docs/cli/reference/idle-pause) |
| Account | [`login`](/docs/cli/reference/login), [`logout`](/docs/cli/reference/logout), [`whoami`](/docs/cli/reference/whoami), [`doctor`](/docs/cli/reference/doctor), [`usage`](/docs/cli/reference/usage), [`config`](/docs/cli/reference/config) |
| Templates | [`template build`](/docs/cli/reference/template-build), [`list`](/docs/cli/reference/template-list), [`info`](/docs/cli/reference/template-info), [`logs`](/docs/cli/reference/template-logs), [`delete`](/docs/cli/reference/template-delete) |
| Coming soon | [`keys`](/docs/cli/reference/keys), [`limits`](/docs/cli/reference/limits), [`push`](/docs/cli/reference/push), [`recover`](/docs/cli/reference/recover) |

`sandbox` (alias `sbx`) groups the lifecycle commands: `anona-compute sbx ls` is `anona-compute list`.

## Output and exit codes

`--json` (or `-o json`) prints JSON on stdout; messages go to stderr. A list command (`list`, `ps`, `template list`, `config list`) prints one JSON array, `[]` when there is nothing to list, so `jq -r '.[].sandbox_id'` reads it at any length; every other command prints one JSON object per line. Every key is snake\_case (`sandbox_id`, `template_id`, `exit_code`), as in the MCP server's tools. An error is one object on stderr: `{"error":{"message":…,"exit_code":…}}`, plus `status`, `error_code` and `request_id` when known, and `"outcome_unknown": true` when a request that creates something failed in a way that does not say whether it was carried out (see [Retries](#retries)).

| Exit code | Meaning |
| - | - |
| 0 | success |
| 1 | general error |
| 2 | usage error: a bad flag, argument or value |
| 3 | not signed in, or the credential was refused |
| 4 | not found |
| 5 | a quota, rate or plan limit (`plan_limit_exceeded`; from CLI 0.4.0, also when the API answers `403`) |

`exec` and `run` exit with the remote command's own exit code, unchanged, so the CLI composes in shell scripts and CI; when the CLI itself fails they exit 125 (as `docker run` does), and the `--json` error keeps the detailed code in `cli_code`. `connect` exits with the shell's exit code. `anona-compute doctor` checks the configuration, the credential and the connection when something does not work.

## Retries

The CLI retries a request at most three times and for at most about a minute, waiting `Retry-After` seconds when the response gives them and backing off otherwise.

* A `Should-Retry` header decides on its own: `true` retries, `false` never does.
* Without it, a `429` is retried, since it is refused before anything happens.
* Without it, a `502`, `503` or `504` is retried for reads, deletes and requests that can safely arrive twice (pause, resume, `timeout`, revoking links).
* Without it, a `502`, `503` or `504` is **not** retried for a request that creates something: `create`, `fork`, a template build, a preview link or a vault secret. Such a response comes from something in front of the API, which cannot know whether the sandbox was already started, and a second create could start a second, billed sandbox. The command fails saying so; list your sandboxes before trying again.

The API's own errors on create always carry `Should-Retry`, so a create still waits out a `503` while the platform starts or has no capacity yet.

`create` and `resume` wait longer than that while the platform has no capacity yet: a `503` with `Should-Retry: true` and `error_code` `sandbox_capacity_unavailable` (a host is starting), `sandbox_engine_starting` (the platform is waking) or `sandbox_size_preparing` (a template is being prepared at a new size) is retried for up to `--capacity-wait`, 10 minutes by default (`ANONA_COMPUTE_CAPACITY_WAIT`; `0` keeps only the short budget above). Each wait follows `Retry-After`, held between 1 and 30 seconds with a little jitter, and prints a line on stderr, so `--json` output stays clean:

```text
anona-compute: waiting for capacity: no host has room yet; a host may be starting, retrying in 30s (1m0s elapsed)
```

`resume --capacity-wait`, the 1 to 30 second bounds and `sandbox_size_preparing` need CLI 0.4.0 or later; 0.3.x waits on `create` only.


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