Skip to main content

arc attach

arc attach reverse-mounts a local directory into a remote arc daemon as a provider, so a machine you don't have shell access to can read your local files through AFS.

arc attach reverse-mounts a local directory into a remote arc daemon, exposing it as a provider under /modules/{namespace} on that remote daemon. This is the opposite direction from arc afs mount: instead of mounting something remote into your local AFS, you're making something local visible to a remote AFS.

Usage

bash
arc attach --to <url> [options]

--to is the only strictly required flag; what else you need depends on which of the three things you're attaching:

  • directory attach (the default): --namespace <name> + --source <dir> — exposes a local directory as a provider mounted at /modules/{namespace} on the remote
  • host attach: --as-host — exports this host's HostFace at /peers/{peer.json.id} on the remote (no --namespace/--source needed)
  • engine attach: --as-engine <name> alone — attaches a bare code-agents engine under that id; combined with --as-host it's just display metadata alongside the HostFace

Options

  • --to <url> (required): target daemon URL, e.g. ws://host:4900 or ws://host:4900/ws/attach
  • --namespace <name>: namespace to expose on the target, mounted at /modules/{namespace} (directory attach)
  • --source <dir>: local directory to expose as the provider (directory attach)
  • --as-engine <name>: engine id alone; with --as-host it's display metadata only (remote id is peer.json's id)
  • --as-host: export this host's HostFace at /peers/{peer.json.id} on the target
  • --readonly: expose the source as read-only (directory attach)
  • --replace: replace an existing session at this namespace
  • --token <token>: owner access token for a remote daemon (skipped for loopback targets)
  • --browser: open a browser for the auth flow (default true); pass --no-browser with --token for unattended runs
  • --json: print machine-readable events on stdout instead of the default human text
  • --view: output view format (json is equivalent to --json)
  • --instance <name> / -i: which local ARC instance this command operates against; omit for default
  • --home <dir>: instance root (where this host's peer.json and credentials live; usually not needed). To pick which instance, use --instance

On SIGINT (Ctrl+C) arc attach detaches gracefully so the remote side unmounts cleanly.

Example

bash
arc attach --to ws://host:4900 --namespace my-local-src --source ./src --readonly
arc attach --to ws://host:4900 --as-host

--json

With --json, every progress line (Attaching..., to:, namespace:, source:, Press Ctrl+C to detach., Detaching...) moves to stderr, and stdout carries only newline-delimited JSON events — a script piping arc attach ... --json can read stdout as pure JSON without filtering out human prose:

bash
$ arc attach --to ws://127.0.0.1:PORT/ws/attach --source /tmp --namespace test --json

stdout (only this one line, on a successful attach):

json
{"event":"attached","sessionId":"sess_test_...","namespace":"test","targetPath":"/modules/test"}

stderr (all progress, banner omitted):

Attaching...
  to:        ws://127.0.0.1:PORT/ws/attach
  namespace: test
  source:    /tmp
Press Ctrl+C to detach.

On a failure, --json does not add a matching JSON object to stdout — stdout stays empty and the error is still the human ERROR: ... line on stderr, for both a validation failure (missing required combination) and a connection failure, exit 5 either way:

bash
$ arc attach --to ws://127.0.0.1:1/ws/attach --source /tmp --json

stdout: (empty)

stderr:

ERROR: attach requires --namespace and --source, or --as-engine, or --as-host
bash
$ arc attach --to ws://127.0.0.1:9/ws/attach --namespace test --source /tmp --json

stdout: (empty)

stderr:

Attaching...
  to:        ws://127.0.0.1:9/ws/attach
  namespace: test
  source:    /tmp
ERROR: attach failed [cockpit-unreachable]: connect ECONNREFUSED 127.0.0.1:9