CLI & Remote Access

The OpenAlice CLI supports two browser-based paths without requiring a source checkout:

• run the installed headless Runtime locally through the Supervisor TUI or explicit lifecycle commands;
• 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.

Stable CLI releases include a checksummed, platform-specific headless Runtime bundle alongside the CLI and managed Pi. Source checkouts remain an advanced development override, not the ordinary startup dependency. 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
                installed headless Runtime
                  └── 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 for the installed Runtime.

The installed Runtime does not require Git or source-build tools. If you explicitly select a source checkout, the approved 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 that source plan requests them. 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

When the install directory is not already active, the success output prints a shell-specific Activate OpenAlice in this terminal now (no restart required) command. Run that exact line, then verify both installed commands:

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

The managed profile block covers future terminals. The activation line reflects your selected --install-dir; fish receives fish_add_path, while POSIX shells receive the appropriate export command.

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 same immutable release contains the CLI, managed Pi, and the matching macOS/Linux headless Runtime. The installer itself does not clone OpenAlice, create application state, or start a service without separate consent.

The installed CLI reports the same version as the OpenAlice product release; there is no separate user-facing CLI version sequence.

Use the local Supervisor

Run the installed Supervisor from any directory:

openalice

Bare openalice opens a terminal UI over the same lifecycle as the explicit commands. Its main controls are:

• Enter starts the selected Runtime and opens the verified Web UI, or opens an already-running AliceProject;
• s, o, x, and r start, open, stop, and restart;
• l reads the bounded redacted log tail, while d runs read-only Doctor;
• u checks for a product update without installing it;
• i selects or creates a named AliceProject with a separate complete home;
• p edits AliceProject or machine defaults for home, Web port, and update checks;
• m and c are advanced managed-source and user-source controls.

Pressing q, Esc, or Ctrl+C detaches from the Supervisor; it does not stop a background Runtime. Stop and restart require confirmation because active Web and Agent Sessions will disconnect. The TUI refuses to stop Electron, development, incompatible, or otherwise foreign owners.

The explicit lifecycle remains useful for scripts:

openalice up [--project <name>]     # detached; wait for real readiness
openalice run [--project <name>]    # foreground; no browser
openalice status [--json]           # read-only normalized status
openalice logs --lines 200 [--json] # bounded, redacted snapshot tail
openalice doctor [--json]           # read-only diagnostics
openalice open                      # verify and open the Web UI
openalice down [--json]             # ask the owning Guardian to stop itself

The installed Runtime is the default provider. A configured source, OPENALICE_APP_HOME, or --app-dir overrides it. Older development installs without a bundle can prepare an installer-channel-aligned managed checkout after explicit confirmation.

up is browserless and idempotent for an already healthy matching owner. down is idempotent when no owner exists. The Runtime does not kill a process merely because a port or PID exists; use --takeover only after inspecting the recorded owner. An Electron- or dev-owned Runtime can be inspected and opened, but down refuses to stop a different owner surface.

Top-level up, down, and status return a versioned envelope with --json. A successful inspection of an absent Runtime still exits 0; automation should read the reported lifecycle class rather than treating nonzero status as “stopped.”

openalice logs reads only bounded regular Runtime log rotations under the selected home and redacts common credential forms before output. Redaction is defense in depth: logs can still contain private product or trading context, so review them before sharing. openalice doctor checks installation provenance, Node.js, Guardian ownership, readiness, components, source-provider artifacts, cached update metadata, and safe log discovery without mutating the Runtime or reading credentials.

openalice start remains the foreground, browser-oriented compatibility path. The older openalice server run|start|status|stop commands remain available for managed remote and existing scripts; both command families operate the same Guardian owner.

Named AliceProjects and complete homes

The Supervisor always has an implicit default AliceProject and can register additional lowercase names through i AliceProjects. Every named project must use a separate complete home; equal or nested homes are rejected. Selecting a project changes the Supervisor view and remembered default but never moves, copies, stops, or deletes another project.

Machine defaults and per-project values live in a Supervisor configuration outside every complete home. Resolution proceeds through stored defaults, project settings, environment variables, and explicit flags, and the UI shows where each effective value came from. OPENALICE_PROJECT, OPENALICE_HOME, OPENALICE_WEB_PORT, OPENALICE_APP_HOME, and OPENALICE_NO_UPDATE_CHECK override stored values for that launch. An explicit project or home fails if unavailable instead of silently falling back to another data set.

Create a named TraderAlice or experimental NanoAlice project from the CLI:

openalice create alice-project
openalice create alice-project --name office --home ~/.openalice-office --product nano --yes
openalice project list
openalice project list --json
openalice project use office

Bare openalice project lists registered homes and can select the remembered default interactively. project use changes the future bare-start target only; it does not start, stop, or copy another project.

AI vault rows have one deliberate cross-project command:

openalice project copy-ai-creds --from default --to office
openalice project copy-ai-creds --from default --to office --yes

The interactive form confirms before writing; non-interactive use requires all three flags. Matching credentials are skipped and colliding slugs are renamed. Workspace launch preferences, broker accounts, and sealing keys remain project-local, and secret values are never printed.

--instance and OPENALICE_INSTANCE remain deprecated aliases for released automation. See AliceProjects for the product, identity, and concurrency contract.

Update, completion, and CLI-only uninstall

An installed public stable-channel CLI performs a short, daily-cached release check before an interactive openalice start. Failure is silent and never blocks startup; discovery prints guidance but never changes files. Starting with v0.89.1-beta, public release installers keep the immutable release tag used for the installed payload separate from the stable update policy. An explicit tag/commit install remains pinned, and development branches and custom installer sources stay inside their selected trust boundary. Use --no-update-check or OPENALICE_NO_UPDATE_CHECK=1 to skip the start check.

Public release installers published before v0.89.1-beta recorded their exact tag in the same shape as a deliberate version pin, so the CLI cannot safely guess the original intent. An affected install remains pinned until you run the public installer once again. That ordinary atomic reinstall preserves application state and records the unambiguous stable update policy for future releases.

Explicit update controls are:

openalice update --check
openalice update --check --json
openalice update
openalice update --yes

An update downloads the release's versioned installer, verifies its published SHA-256, and hands off to the ordinary visible install plan. It retains the old content-addressed release and never installs without the normal consent unless --yes is explicit.

Shell completion is generated without editing shell configuration:

openalice completion bash
openalice completion zsh
openalice completion fish
openalice completion powershell

To remove only installer-owned CLI assets:

openalice uninstall --plan
openalice uninstall
openalice uninstall --yes

CLI uninstall removes the installed openalice/pi launchers, immutable CLI releases, its lock/cache, and matching managed PATH blocks. It preserves application state, Workspaces, managed source checkouts, credentials, provider-keys.json, sealing.key, and backups.

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, managed Pi, and platform Runtime;
2. verify and start the detached Guardian-owned Server;
3. open a local loopback tunnel.

The Runtime lives in the installer's immutable release directory. The plan names 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.

If the tunnel later becomes unreachable, the global offline screen can distinguish that remote SSH route from a local Runtime outage and show the SSH destination, SSH port, and remote loopback Runtime port to retry. openalice ssh and openalice remote pass only that validated routing identity in a short-lived URL fragment. The browser consumes it into tab-scoped session storage and immediately removes it from the address bar; fragments are not sent in HTTP requests and do not become remote Runtime state or server log data.

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 durable state on persistent storage.
openalice remote openalice-box \
  --home /data/openalice-home

Use a volume-backed --home on an ephemeral VM or container. The Runtime can be reinstalled; the complete home is the durable state. A provider replacement can reattach a volume whose Guardian lock names the removed machine; OpenAlice will refuse automatic cross-machine takeover. Confirm the previous AliceProject owner is gone before following recovery guidance.

Installed Runtime and user-owned source

By default, local and managed-remote startup use the verified Runtime bundled with the installed OpenAlice release. It has its own manifest identity and does not require a repository checkout.

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 remote 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. Source-build tools are requested only for this advanced path.

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.
• CLI and Runtime assets are release-owned and checksum-verified, but are not yet independently cryptographically 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.
• AliceProjects — Understand project identity and concurrent runtimes.
• AI Providers — Configure a model where the Runtime lives.
• Source & Dev — Work directly from a checkout.