aicomputer

Agent Computer CLI for creating, opening, and managing computers from the terminal.

Install

npm install -g aicomputer

On macOS and Linux, the npm install and update flow also installs the CLI-managed Mutagen binary used by computer mount.

Upgrade the installed CLI later with:

computer upgrade

Or run it directly with Nix:

nix run github:getcompanion-ai/agentcomputer?dir=apps/cli -- login

For local testing from this checkout, prefer:

nix run path:./apps/cli -- --version

To declare it in a flake-based Nix config:

{
  inputs.agentcomputer-cli = {
    url = "github:getcompanion-ai/agentcomputer?dir=apps/cli";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

home.packages = [
  agentcomputer-cli.packages.${pkgs.system}.default
];

# or

environment.systemPackages = [
  agentcomputer-cli.packages.${pkgs.system}.default
];

Private Repo Rollout

To keep Nix distribution aligned with the npm CLI release flow for this private repo:

1. Create a Cachix cache for the CLI.
2. Add a GitHub Actions repository variable named CACHIX_CACHE with that cache name.
3. Add a GitHub Actions repository secret named CACHIX_AUTH_TOKEN with a write token for that cache.
4. Run the CLI Release workflow or push a cli-v* tag.

The release workflow will:

• build the CLI with npm ci
• build the Nix package
• sync apps/cli/package-lock.json and apps/cli/package.nix when the CLI version changes
• publish the npm package
• push the built Nix closure to the configured Cachix cache

Consumers should add the binary cache to their Nix config:

nix.settings = {
  substituters = [
    "https://cache.nixos.org"
    "https://<your-cache>.cachix.org"
  ];
  trusted-public-keys = [
    "<your-cache>.cachix.org-1:<your-public-key>"
  ];
};

Usage

After installing, use the computer command:

computer login
computer upgrade
computer login --api-key <ac_live_...>
computer claude-login
computer codex-login
computer whoami
computer create my-box
computer power-off my-box
computer power-on my-box
computer open my-box
computer ssh
computer ssh my-box
computer ssh my-box --tmux
computer ssh --setup
computer ssh my-box -N -L 3000:localhost:3000
computer mount
computer mount --background
computer mount status
computer agent agents my-box
computer agent sessions list my-box
computer agent prompt my-box "inspect /home/node" --agent codex
computer acp serve my-box --agent codex

computer login authenticates the CLI against Agent Computer. Use computer claude-login and computer codex-login to install Claude Code or Codex credentials onto a machine after the CLI is already logged in. Use computer upgrade to update a global npm install or the matching Nix profile entry.

Use computer power-off to stop a managed worker without deleting its durable home volume. Use computer power-on to recreate the runtime against the same stored machine and home state.

Run computer ssh without a handle in an interactive terminal to pick from your available machines.

Run computer ssh --setup once to register your SSH key and add a global alias:

ssh agentcomputer.ai
ssh [email protected]

Use computer ssh <handle> <ssh args> when you want the CLI to resolve the machine and identity while still passing standard SSH tunnel flags through to the underlying client. Long-running SSH sessions and forwarded tunnels stay on the same resilient path:

computer ssh my-box -N -L 3000:localhost:3000

computer ssh now launches through autossh by default. Nix installs package ssh, scp, and autossh together. Global npm installs on macOS and Linux provision Agent Computer's bundled autossh copy during postinstall and retry that install on first SSH use if npm scripts were skipped. npm users still need local OpenSSH client tools available.

Use computer ssh <handle> --tmux when you want reconnects to reattach to the same remote shell session instead of dropping you into a fresh shell. The flag attaches to tmux new-session -A -s agentcomputer, so it is meant for interactive shells, not -N tunnels or other non-interactive SSH flows.

Run computer mount to start the mount controller in the foreground and mirror all SSH-ready machine homes under ~/agentcomputer/<handle>. On macOS, the foreground command also opens Finder to ~/agentcomputer after the controller starts.

Run computer mount --background to start the same controller detached from your terminal. It prints the controller PID immediately so you can inspect it later with computer mount status.

This uses the same SSH setup as computer ssh --setup. For npm installs on macOS and Linux, the CLI auto-installs its bundled Mutagen copy and will retry that install on first mount if npm scripts were skipped. You still need the OpenSSH client tools (ssh and scp) available locally. The temporary ~/agentcomputer root is removed when the command exits.

Use computer agent to inspect agents on one machine and manage remote sessions. Use computer acp serve when you want to expose one remote session through a local ACP bridge.

You can also run without a global install via npx aicomputer <command>.