# How to run Amp in a cloud sandbox

Install the Amp CLI with its script in a Linux microVM, 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, and the host's proxy adds the real token on requests to `ampcode.com`.
Each sandbox is a Firecracker microVM with its own Linux kernel and Ubuntu
24.04, so 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 September 2026 was `0.0.1790294503-g39c830`.

| 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 `amp login` stores). Then:

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

Every sandbox of your account starts with `AMP_API_KEY` set to a placeholder.
The CLI hands the value to Amp's server rather than checking it locally, which
is why the placeholder works: the proxy puts the real token into HTTPS
requests to `ampcode.com` and no other host
([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, so the CLI 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 is watching an execute-mode run, and 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, a Claude Code-compatible JSON event stream.
- **The allow list** covers Amp's service at `ampcode.com` and the hosts
  under it, such as `static.ampcode.com`, which serves the CLI's builds, plus
  npm for the project's installs.
- **The patch** is written inside the sandbox and read back, so it never hits
  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 is about
the local form.

## Execute-mode reference

From Amp's execute-mode page and `amp --help`, 25 September 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: `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, the
same JSON goes in `--mcp-config` instead. Amp asks you to approve MCP servers
found in a workspace's `.amp/settings.json` before they start, so user-level
settings are the simpler place.

| Tool                      | What Amp gains                                      |
| ------------------------- | --------------------------------------------------- |
| `runtime_sandbox_create`  | A microVM for code it should not run on your laptop |
| `runtime_sandbox_exec`    | Builds and tests there, with exit codes             |
| `runtime_sandbox_mount`   | Your S3, R2 or GCS bucket as a directory            |
| `runtime_snapshot_create` | 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, and $0.0075 per GiB-hour of reserved memory. At 2
vCPUs and 4 GiB that is $0.03125 an hour while Amp's models work and $0.08 an
hour with both cores busy ([pricing](/docs/pricing)). Amp bills its model use
to your Amp account. Start with 50 free sandbox hours, no card:

```bash no-run
npx withruntime sandbox run --trial -- 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 once.

## Sources

Checked 25 September 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.1790294503-g39c830`, whose `amp --help` lists `amp.dangerouslyAllowAll`,
  `--stream-json` and `--mode`; run with a placeholder token on 25 September
  2026, it sent the token to `ampcode.com` rather than rejecting it locally

Facts on this page were checked on 25 September 2026.