{
  "id": "page:docs-agent-mux-tutorials-remote-bootstrap",
  "_kind": "Page",
  "_file": "wiki/docs/agent-mux/tutorials/remote-bootstrap.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-mux/tutorials/remote-bootstrap.md",
    "sourceKind": "repo-docs",
    "title": "Remote bootstrap",
    "displayName": "Remote bootstrap",
    "slug": "docs/agent-mux/tutorials/remote-bootstrap",
    "articlePath": "wiki/docs/agent-mux/tutorials/remote-bootstrap.md",
    "article": "\n# Remote bootstrap\n\nThe `agent-mux-remote` adapter lets you drive a coding agent that runs on a\nremote host — over SSH, in a container, or behind a gateway. \"Bootstrap\" is\nthe process of getting the remote side ready: installing `amux`, wiring\ncredentials, and establishing a session channel.\n\n## 1. Install on the remote host\n\n```bash\n# On the remote machine\ncurl -fsSL https://nodejs.org/dist/v22.x/node-v22.x-linux-x64.tar.xz | tar -xJ\nnpm i -g @a5c-ai/agent-mux-cli\n```\n\nOr use the built-in bootstrap command, which copies an install script over\nSSH and runs it:\n\n```bash\namux remote bootstrap user@host --agent claude\n```\n\nThis installs the CLI, ensures the target harness (e.g. `@anthropic-ai/claude-code`)\nis present, and writes a minimal `~/.amux/config.json` on the remote.\n\n## 2. Configure credentials\n\nThe remote host needs the same env vars (or config files) that the local\nsetup would need. Options:\n\n- **env-forward** (default): `amux` forwards `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` /\n  etc. from the local shell into the SSH session for the lifetime of the run.\n- **config-file**: pre-seed `~/.claude/auth.json` (or equivalent) on the remote\n  so the harness authenticates without env vars.\n- **per-call**: pass `env: { ANTHROPIC_API_KEY: '…' }` to `run()`.\n\n## 3. Running against the remote\n\n```ts\nimport { AgentMuxClient } from '@a5c-ai/agent-mux';\n\nconst client = new AgentMuxClient();\nconst handle = await client.run({\n  agent: 'agent-mux-remote',\n  remote: { host: 'user@host', agent: 'claude' },\n  prompt: 'Summarize the repository in two paragraphs.',\n});\n\nfor await (const ev of handle.events()) {\n  if (ev.type === 'text_delta') process.stdout.write(ev.text);\n}\n```\n\nFrom the CLI:\n\n```bash\namux run agent-mux-remote \\\n  --remote-host user@host \\\n  --remote-agent claude \\\n  \"Summarize the repository.\"\n```\n\n## 4. Invocation modes\n\nThe remote adapter respects agent-mux's invocation modes:\n\n- `mode: 'host'` — spawn the remote CLI directly (SSH exec).\n- `mode: 'docker'` — run the remote CLI inside a container on the remote host.\n- `mode: 'k8s'` — submit the remote CLI as an ephemeral pod.\n\nSee [docker-mode](./docker-mode.md) and [k8s-mode](./k8s-mode.md) for the\ncontainer flavors — the same flags apply to `agent-mux-remote`.\n\n## 5. Tearing down\n\n`amux remote teardown user@host` removes `~/.amux/`, the installed harness\n(if you used `bootstrap`), and any cached sessions. Use `--keep-sessions` to\npreserve the history directory.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-mux-tutorials",
      "to": "page:docs-agent-mux-tutorials-remote-bootstrap",
      "kind": "contains_page"
    }
  ]
}