CLI & Remote Access

The stable OpenAlice CLI supports two browser-based paths:

• run a source checkout on your own computer with openalice start;
• keep the browser on your laptop while openalice remote prepares and runs OpenAlice on a private Linux or macOS host.

Remote access follows the same ownership idea as Herdr: the machine with the files owns execution and durable state, while the local client can disconnect and return. OpenAlice keeps its normal browser UI and carries HTTP, APIs, Workspace terminals, and WebSockets through an ordinary SSH loopback tunnel.

The CLI path remains source-backed; it is not yet a signed standalone headless bundle. It is nevertheless a supported first-class private-host path. Docker is the parallel first-class server option when you want an image, volume, healthcheck, bundled Agent CLIs, and a container-owned lifecycle.

Choose the right surface

Remote mental model

laptop
  openalice remote
    └── ssh -L 127.0.0.1:<local-port>:127.0.0.1:47331
          └── remote host
                managed source checkout
                  └── Guardian-owned OpenAlice Server
                        ├── Alice HTTP + Workspace WebSocket
                        ├── Workspace files and Sessions
                        ├── managed Pi and native Agent processes
                        └── optional UTA and Connector Service

laptop browser
  └── http://127.0.0.1:<local-port>

The remote Runtime stays on loopback. OpenSSH continues to own authentication, encryption, host verification, keys, agents, proxy jumps, and port policy. OpenAlice does not invent a second SSH credential system.

Prerequisites

On the laptop:

• macOS, Linux, or WSL;
• Node.js 22.19.0 or newer;
• curl and OpenSSH;
• working SSH access to the target.

On the remote host:

• Linux or macOS;
• Node.js 22.19.0 or newer;
• curl;
• enough disk and memory to install and build OpenAlice.

The approved remote plan can install missing Git, Python 3, make, and C++ tools on supported Linux hosts. On macOS, install Command Line Tools locally with xcode-select --install when requested. OpenAlice does not install Node.js or create SSH keys.

An SSH alias keeps later commands short:

Host openalice-box
  HostName server.example.com
  User alice
  IdentityFile ~/.ssh/id_ed25519

Verify it once:

ssh openalice-box

Exit that shell after it connects.

Install the stable CLI

curl -fsSL https://openalice.ai/install | bash

Open a new terminal and verify both installed commands:

openalice --version
openalice version --json
pi --version

The installer shows a complete plan and proceeds only after an explicit y. Blank input or n changes nothing. Non-interactive use requires --yes; --plan is always read-only. The installed CLI records its branch, tag, or commit plus an immutable payload identity, so managed remote can reproduce the same control payload instead of relying on a human version string alone.

The installer itself does not clone OpenAlice. Local source use remains user-owned; managed remote owns its separate, visible clone step.

Run a local source Runtime

From an existing checkout:

cd OpenAlice
openalice start

Useful lifecycle commands:

openalice server run
openalice server start
openalice server status
openalice server status --json
openalice server stop

The Runtime reuses a healthy compatible owner for the same data home. It does not kill a process merely because a port or PID exists. Use --takeover only after inspecting the recorded owner.

Connect to a remote host

1. Review the plan

openalice remote openalice-box --plan

No checkout path is required. On a new host the plan normally proposes:

1. install the matching OpenAlice CLI and managed Pi;
2. install missing Linux source-build tools, if needed;
3. clone a selector-specific managed source checkout;
4. build and start a detached Guardian-owned Server;
5. open a local loopback tunnel.

The managed checkout lives under the selected remote OPENALICE_HOME in a private sources/ directory. The plan names the exact path and every mutation before consent. A read-only plan changes no remote files or processes.

2. Apply and connect

openalice remote openalice-box

Approve the plan. First preparation can take several minutes. Successful install and build phases stay compact; failures include a bounded diagnostic tail. When ready, OpenAlice opens a local URL such as http://127.0.0.1:49891.

The browser, APIs, and Workspace terminal WebSocket use the same tunnel. Agent processes, Workspaces, credentials, and optional trading services remain on the remote machine.

Everyday use

Reconnect with the short command:

openalice remote openalice-box

OpenAlice prefers the last successful local port, allowing an existing browser tab to recover on the same localhost origin. If the port is genuinely busy, it selects another one and reports the change.

Inspect or stop the Server without composing raw SSH commands:

openalice remote openalice-box --status
openalice remote openalice-box --stop

Status uses one bundled SSH control probe instead of repeating the full bootstrap scan. Stop asks the owning Guardian to shut down its own tree and verifies the absent state.

Closing the browser or pressing Ctrl+C closes only the local tunnel. The detached Server, Workspaces, PTYs, and Agent processes continue until stopped or the host shuts down.

Known transient SSH interruptions are retried with a short neutral message. Provider-specific diagnostics are held back unless the operation finally fails, so temporary control-plane noise is not treated as normal user output.

Useful variations:

# Keep one explicit browser origin.
openalice remote openalice-box --local-port 49891

# Print the URL without opening a browser.
openalice remote openalice-box --no-open

# Use an identity without an SSH config alias.
openalice remote alice@server.example.com \
  --identity ~/.ssh/id_ed25519

# Keep state and the managed checkout on persistent storage.
openalice remote openalice-box \
  --home /data/openalice-home

Use a volume-backed --home on an ephemeral VM or container. The managed source follows that home onto the same storage. A provider replacement can reattach a volume whose Guardian lock names the removed machine; OpenAlice will refuse automatic cross-machine takeover. Confirm the previous instance is gone before following recovery guidance.

Managed and user-owned source

By default OpenAlice owns the managed checkout:

• a missing checkout is cloned atomically after consent;
• a clean branch checkout is compared with its selected upstream on reconnect;
• an available fast-forward is shown in the plan, then rebuilt and restarted;
• tracked local changes block the update instead of being overwritten.

For development or a deliberately pinned checkout, pass an absolute path:

openalice remote openalice-box \
  --app-dir /srv/OpenAlice

If the path is absent, the approved plan can clone there. If it already contains OpenAlice, it remains user-owned: managed remote can prepare and start it but never fetches, switches, resets, or overwrites it. An occupied non-OpenAlice path is refused.

Security and persistence

• Do not publish remote port 47331 directly for the SSH path.
• Never set OPENALICE_DISABLE_AUTH=1 for remote access.
• Use a least-privilege remote account and normal SSH host-key discipline.
• Back up the complete remote OPENALICE_HOME; the browser is not a backup.
• The source-backed CLI payload is release-owned but not yet independently signed.
• Native Windows remote hosting is not supported; use Linux/WSL or the desktop package.

For a container reached through LAN, Tailscale, or private HTTPS, use Docker. Docker users are not expected to replace their deployment with SSH remote, and remote users are not expected to wrap an existing machine in Docker.

Next steps

• Docker — Run the first-class container topology.
• Data & Credentials — Select and back up a complete home.
• AI Providers — Configure a model where the Runtime lives.
• Source & Dev — Work directly from a checkout.