Skip to main content

agent-mux-remote

Meta-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.

Install​

amux install agent-mux-remote

Supported on macOS, Linux and Windows.

Auth​

Auth is delegated to the invocation mode:

  • local — reuse the current shell's env.
  • ssh — SSH config / keys.
  • docker — Docker context; env vars are passed via -e.
  • k8s — kubectl context.

The adapter itself has no credentials of its own.

Minimal run​

AMUX_REMOTE_AGENT=claude \
  amux run agent-mux-remote --prompt "Hello from a container"

Or explicitly:

await client.run({
  agent: 'agent-mux-remote',
  prompt: 'Hello',
  invocationMode: { kind: 'docker', image: 'my/amux:latest' },
  env: { AMUX_REMOTE_AGENT: 'claude' },
});

Notable flags​

The adapter emits:

amux run --json --agent <AMUX_REMOTE_AGENT> --prompt <text>
    [--model <id>] [--session <id>] [--yolo|--deny]

The invocation mode (ssh/docker/k8s) wraps these args. See Invocation Modes.

Session files​

  • sessionDir() returns '' — sessions live on the remote target under that agent's own session directory.

Plugins​

Plugin support: no. Use MCP servers for extensibility.

MCP Servers​

amux mcp install agent-mux-remote <mcp-server>
amux mcp list agent-mux-remote

Registry: https://modelcontextprotocol.io

Known limitations​

  • No bundled models — defaultModelId is undefined. You must pick the model via RunOptions.model according to the remote agent.
  • No config schema of its own; config lives with the remote agent.
  • Session resume works only if the remote agent supports it and the session file is reachable on the target.
  • Because events are proxied, extra latency vs. running locally.