# How to run Amp in a cloud sandbox

Install the Amp CLI in a Linux microVM with its install script. Store the Amp access token as a secret. Then run `amp -x "<task>"`.

**On Runtime, Amp's execute mode gets a whole machine, and your access token
stays off it.** Amp's CI guide has you put an access token in `AMP_API_KEY`.
Stored as a Runtime secret, that variable holds only a placeholder inside the
sandbox. The host's proxy adds the real token to requests to `ampcode.com`.
Each sandbox is a Firecracker microVM with its own Linux kernel and Ubuntu
24.04. The CLI's Linux build installs as it would on any server. While the
agent waits on Amp's models, a 2 vCPU, 4 GiB sandbox costs $0.03125 an
hour. The CLI build current on 25 October 2026 was `0.0.1792972877-g78a0d4`.

| Amp runs             | Runtime's part                                           |
| -------------------- | -------------------------------------------------------- |
| In a Runtime sandbox | The machine: shell, files and network, driven by the SDK |
| On your own machine  | An MCP server whose tools create and run sandboxes       |

## The access token as a secret

Create an access token in Amp's settings. It starts with `sgamp_`. Amp's CLI
refuses the short-lived token that `amp login` stores. Then run:

```bash no-run
printf %s "$AMP_API_KEY" | npx withruntime secrets set AMP_API_KEY --host ampcode.com
```

Every sandbox in your account starts with `AMP_API_KEY` set to a placeholder.
The CLI passes the value to Amp's server rather than checking it locally. That
is why the placeholder works. The proxy puts the real token into HTTPS requests
to `ampcode.com`, and into no other host's requests
([secrets sandboxes never see](/docs/security#secrets-sandboxes-never-see)).

Amp's own proxy guide names `HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS` for
corporate networks. The sandbox image sets both. The CLI therefore trusts the
proxy that adds the token, with no extra setup.

## Execute mode on a repo

```ts check
import { writeFile } from "node:fs/promises";
import { Sandbox } from "withruntime";

const repo = "https://github.com/your-org/your-repo";
const task =
  "Find every place the API returns a 500 for bad input, return a 400 instead, and add tests.";

await using sbx = await Sandbox.create({ diskMiB: 8192, timeoutSeconds: 3600 });
const setup = { check: true, timeoutMs: 600_000 } as const;
await sbx.exec("curl -fsSL https://ampcode.com/install.sh | bash", setup);
await sbx.exec(["git", "clone", "--depth", "1", repo, "/workspace/app"], setup);
await sbx.files.write(
  "/workspace/.config/amp/settings.json",
  JSON.stringify({ "amp.dangerouslyAllowAll": true }),
);

await sbx.network.set({
  internet: true,
  allow: ["ampcode.com", "*.ampcode.com", "registry.npmjs.org"],
});

const run = await sbx.exec(["amp", "-x", task, "--stream-json"], {
  cwd: "/workspace/app",
  timeoutMs: 1_800_000,
  onStderr: (text) => process.stderr.write(text),
});
const events = run.stdout
  .split("\n")
  .filter(Boolean)
  .map((line) => JSON.parse(line));
console.log(run.exitCode, events.at(-1));

await sbx.exec("git add -A && git diff --cached > /workspace/amp.patch", {
  cwd: "/workspace/app",
  check: true,
});
await writeFile("amp.patch", await sbx.files.readText("/workspace/amp.patch"));
```

```python check
import sys, json
from withruntime import Sandbox

repo = "https://github.com/your-org/your-repo"
task = "Find every place the API returns a 500 for bad input, return a 400 instead, and add tests."

with Sandbox.create(disk_mib=8192, timeout_seconds=3600) as sbx:
    sbx.exec("curl -fsSL https://ampcode.com/install.sh | bash",
             check=True, timeout_ms=600_000)
    sbx.exec(["git", "clone", "--depth", "1", repo, "/workspace/app"],
             check=True, timeout_ms=600_000)
    sbx.files.write("/workspace/.config/amp/settings.json",
                    json.dumps({"amp.dangerouslyAllowAll": True}))

    sbx.network.set(internet=True,
                    allow=["ampcode.com", "*.ampcode.com", "registry.npmjs.org"])

    run = sbx.exec(["amp", "-x", task, "--stream-json"], cwd="/workspace/app",
                   timeout_ms=1_800_000, on_stderr=sys.stderr.write)
    events = [json.loads(line) for line in run.stdout.splitlines() if line]
    print(run.exit_code, events[-1] if events else None)

    sbx.exec("git add -A && git diff --cached > /workspace/amp.patch",
             cwd="/workspace/app", check=True)
    with open("amp.patch", "w") as file:
        file.write(sbx.files.read_text("/workspace/amp.patch"))
```

How it works:

- **The install script** puts the binary in `~/.amp/bin` and links `amp` into
  `~/.local/bin`. In a sandbox, `HOME` is `/workspace`, and
  `/workspace/.local/bin` is already first on `PATH`.
- **`amp.dangerouslyAllowAll`** in `~/.config/amp/settings.json` turns off
  every command confirmation. Nobody watches an execute-mode run. The microVM
  is the boundary, so the agent may run anything inside it.
- **`-x`** sends the task, waits for the agent to end its turn, prints the
  final message and exits. Without `--stream-json`, you get that one message as
  plain text. With it, you get a Claude Code-compatible JSON event stream.
- **The allow list** covers Amp's service at `ampcode.com` and the hosts
  under it. One example is `static.ampcode.com`, which serves the CLI's builds.
  It also covers npm for the project's installs.
- **The patch** is written inside the sandbox and read back. It never reaches
  the 64 KiB limit on returned output.

`-x` runs the agent locally, which here means inside your sandbox. Amp's
`-ox` sends a task to an orb on Amp's own servers instead. This page covers
only the local form.

## Execute-mode reference

From Amp's execute-mode page and the CLI build, 25 October 2026:

| Flag or setting            | Effect                                         |
| -------------------------- | ---------------------------------------------- |
| `-x`, `--execute "<task>"` | One turn, final message printed, then exit     |
| stdout redirected          | Turns execute mode on by itself                |
| `--stream-json`            | JSON events instead of plain text              |
| `--mcp-config '<json>'`    | MCP servers for this run only                  |
| `-m`, `--mode <mode>`      | Agent mode: `low`, `medium`, `high` or `ultra` |
| `--title <title>`          | Title of the new thread                        |
| `amp.dangerouslyAllowAll`  | No confirmation prompts for commands           |
| `AMP_API_KEY`              | Access token for non-interactive use           |

Piped input and `-x` combine. For example, `git diff | amp -x "review this"`
gives the agent both. To keep a checkout for the next task,
[pause the sandbox](/how-to/pause-and-resume-a-sandbox) instead of stopping it.

## Add Runtime to Amp

With Amp on your laptop, one command adds Runtime's MCP server. Everything
after `--` is the command Amp starts:

```bash no-run
amp mcp add runtime -- npx -y withruntime mcp
```

Or put it in `~/.config/amp/settings.json`:

```json no-run
{
  "amp.mcpServers": {
    "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] }
  }
}
```

The first Runtime call prints a link and a code. Approve **Connect agent** in
the browser, and the tools load. No key goes in Amp's settings
([MCP](/docs/mcp#add-it-to-your-agent)). For a single execute-mode run, put the
same JSON in `--mcp-config` instead. Amp asks you to approve MCP servers found
in a workspace's `.amp/settings.json` before they start. User-level settings
are therefore the simpler place.

| Tool                       | What Amp gains                                      |
| -------------------------- | --------------------------------------------------- |
| `runtime_sandboxes_create` | A microVM for code it should not run on your laptop |
| `runtime_sandboxes_exec`   | Builds and tests there, with exit codes             |
| `runtime_sandboxes_mounts` | Your S3, R2 or GCS bucket as a directory            |
| `runtime_snapshots`        | A saved starting point for later copies             |

## Cost

Runtime charges for CPU the sandbox uses at $0.025 per vCPU-hour, with a
floor of a twentieth of a vCPU. Reserved memory is charged at $0.0075 per
GiB-hour. At 2 vCPUs and 4 GiB, a sandbox costs $0.03125 an hour while
Amp's models work. It costs $0.08 an hour with both cores busy
([pricing](/docs/pricing)). Amp bills its model use to your Amp account. A new
account gets 100 free hours of a 1 GB machine in its first 30 days. No card is needed:

```bash no-run
npx withruntime sandboxes run -- uname -a
```

For the same pattern with other agents, see [Claude Code](/integrations/claude-code)
and [Cline](/integrations/cline).
[A sandbox for coding agents](/use-cases/coding-agent-sandbox) covers running
many tasks at the same time.

## Sources

Checked 25 October 2026.

- [Amp CLI](https://ampcode.com/docs/cli): the Linux CLI and
  `curl -fsSL https://ampcode.com/install.sh | bash`
- [install.sh](https://ampcode.com/install.sh): `~/.amp/bin`, the link in
  `~/.local/bin`, downloads from `static.ampcode.com`
- [Execute mode](https://ampcode.com/docs/cli/execute-mode): `-x`, piping,
  `--mcp-config`, `AMP_API_KEY` and `sgamp_` tokens
- [Configuration](https://ampcode.com/docs/cli/settings): settings paths,
  `amp.mcpServers`, `HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS`
- [MCP](https://ampcode.com/docs/customize/mcp): `amp mcp add` and workspace
  server approval
- [@ampcode/cli on npm](https://www.npmjs.com/package/@ampcode/cli): build
  `0.0.1792972877-g78a0d4`, whose binary carries the `amp.dangerouslyAllowAll`
  setting, `--stream-json` and `--mode`. An earlier build, run with a placeholder
  token on 25 September 2026, sent the token to `ampcode.com` rather than
  rejecting it locally.

Facts on this page were checked on 25 October 2026.