{
  "id": "page:docs-agent-mux-reference-agents-agent-mux-remote",
  "_kind": "Page",
  "_file": "wiki/docs/agent-mux/reference/agents/agent-mux-remote.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-mux/reference/agents/agent-mux-remote.md",
    "sourceKind": "repo-docs",
    "title": "agent-mux-remote",
    "displayName": "agent-mux-remote",
    "slug": "docs/agent-mux/reference/agents/agent-mux-remote",
    "articlePath": "wiki/docs/agent-mux/reference/agents/agent-mux-remote.md",
    "article": "\n# agent-mux-remote\n\nMeta-adapter that invokes `amux` on a **remote target** (SSH host, Docker container, or Kubernetes pod) and bridges its event stream back to the local client. Useful for running any supported agent in an isolated or remote environment.\n\n## Install\n\n```bash\namux install agent-mux-remote\n```\n\nSupported on macOS, Linux and Windows.\n\n## Auth\n\nAuth is delegated to the invocation mode:\n\n- `local` — reuse the current shell's env.\n- `ssh` — SSH config / keys.\n- `docker` — Docker context; env vars are passed via `-e`.\n- `k8s` — kubectl context.\n\nThe adapter itself has no credentials of its own.\n\n## Minimal run\n\n```bash\nAMUX_REMOTE_AGENT=claude \\\n  amux run agent-mux-remote --prompt \"Hello from a container\"\n```\n\nOr explicitly:\n\n```ts\nawait client.run({\n  agent: 'agent-mux-remote',\n  prompt: 'Hello',\n  invocationMode: { kind: 'docker', image: 'my/amux:latest' },\n  env: { AMUX_REMOTE_AGENT: 'claude' },\n});\n```\n\n## Notable flags\n\nThe adapter emits:\n\n```\namux run --json --agent <AMUX_REMOTE_AGENT> --prompt <text>\n    [--model <id>] [--session <id>] [--yolo|--deny]\n```\n\nThe **invocation mode** (ssh/docker/k8s) wraps these args. See [Invocation Modes](../13-invocation-modes.md).\n\n## Session files\n\n- `sessionDir()` returns `''` — sessions live on the remote target under that agent's own session directory.\n\n## Plugins\n\nPlugin support: **no**. Use MCP servers for extensibility.\n\n### MCP Servers\n```bash\namux mcp install agent-mux-remote <mcp-server>\namux mcp list agent-mux-remote\n```\n\nRegistry: https://modelcontextprotocol.io\n\n## Known limitations\n\n- No bundled models — `defaultModelId` is `undefined`. You must pick the model via `RunOptions.model` according to the remote agent.\n- No config schema of its own; config lives with the remote agent.\n- Session resume works only if the remote agent supports it and the session file is reachable on the target.\n- Because events are proxied, extra latency vs. running locally.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-mux-reference",
      "to": "page:docs-agent-mux-reference-agents-agent-mux-remote",
      "kind": "contains_page"
    }
  ]
}