Documentation

Install a remote agent, connect Claude or another MCP client — or just call the plain REST API — and run shell commands on machines you own without exposing inbound ports.

Quick Start

The fastest path to Claude running commands on a target machine.

1. Install the agent on the target machine

   The agent runs on the machine you want to control. Pick that machine's operating system — Linux uses a one-line CLI installer, while macOS and Windows use the desktop app (which bundles the agent):

   macOS Windows Linux

   Download the desktop app and open it — there is no CLI installer on macOS. The agent is bundled inside, so the menu-bar icon shows the current session code and lets you copy it.

   Download for macOS

   Apple Silicon (M1–M4) · Intel (x64)

   Download the desktop app and open it — there is no CLI installer on Windows. The agent is bundled inside, so the tray icon shows the current session code and lets you copy it.

   Download for Windows

   Windows x64

   SSH into the machine and run the one-line installer:

   $ curl -fsSL https://aicommander.dev/install | sudo bash

   The installer downloads a standalone native binary for your architecture (x86_64 or arm64), installs it as a systemd service, starts it immediately, and opens an outbound WebSocket to the relay. Read the session code from logs (or run sudo aicommander-agent status):

   $ journalctl -u aicommander-agent -f
   
   # Output:
   ✓ Registered with relay
     Session: AIC-7K3P-WX9M-RTBN

   However you install it, the agent registers with the relay and produces a stable session code like AIC-7K3P-WX9M-RTBN — that code is how you address the machine.

2. Connect your AI client

   Pick your client and run the one-line command — no token needed:

   Claude Code Codex opencode pi

   $ claude mcp add --transport http aicommander https://aicommander.dev/mcp

   $ codex mcp add aicommander --url https://aicommander.dev/mcp

   $ opencode mcp add aicommander --url https://aicommander.dev/mcp

   $ pi install npm:@aicommander/mcp

   Using a GUI editor, ChatGPT, or no MCP at all? See Connect a client for every option — custom connector, plain REST, or the Agent Skill.

3. Talk to your machine

   Mention the session code anywhere in your Claude conversation:

   "Show me disk usage on AIC-7K3P-WX9M-RTBN"
   "Install nginx on AIC-9F4D-2HQN-VK7T and show me the service status"
   "What's the memory usage on AIC-3M8R-PW6H-XJ2C?"

   Claude detects the AIC- prefix and can use the remote_exec tool. The command runs on the machine for that code, and stdout/stderr stream back to the conversation.

4. Optional: name your machines

   Tired of quoting AIC-… codes? Sign in (magic link, no password) and the machine auto-links to your account on first use, saved under a friendly alias — then just say "check the disk on prod-server" instead of the code. Signing in also lets you keep using the machine indefinitely (via the alias or the raw code) — long past the first hour — until the owner resets the code or blocks your account. See Security.

Agent Installation

The agent is what runs on the machine you want to control. Pick your platform — the download or install command updates below:

Platform reference follows.

Linux — CLI installer (recommended for servers)

The install script detects your CPU architecture, downloads a single standalone native binary (no Node, no npm), and installs it as a systemd service that starts on boot. By default it runs as root so shell commands behave like remote administration commands.

$ curl -fsSL https://aicommander.dev/install | sudo bash

Supported targets:

• Linux x86_64 — creates a systemd unit (aicommander-agent.service)
• Linux arm64 (e.g. Raspberry Pi, ARM servers) — same systemd unit

The agent binary doubles as its own service controller:

$ sudo aicommander-agent status        # session code, uptime, state
$ sudo aicommander-agent change-code   # mint a NEW code — old code dies, clears ALL links & blocks (prompts; --yes to skip)
$ sudo aicommander-agent list-admins   # accounts linked to this machine (masked emails)
$ sudo aicommander-agent block-admin 2  # block one account by list number / id (any time)
$ sudo aicommander-agent unblock-admin 2 # unblock to restore that account's access
$ sudo aicommander-agent disable       # stop and disable on boot
$ sudo aicommander-agent uninstall --force

list-admins shows every account currently linked to this machine; emails are masked (e.g. lu****@wear****.com) and never leave the relay unmasked. block-admin blocks one account at any time — it refuses that account's access and stops it re-linking, but the account stays listed (in a "Blocked" section) so unblock-admin restores it instantly. To lock everyone out at once, reset the code instead. See Security.

macOS & Windows — desktop app

Download the desktop app from the home page (DMG for macOS Apple Silicon / Intel, EXE for Windows x64). It bundles the agent: launch it, and the menu-bar / tray icon shows the current session code and lets you copy it, refresh it ("Reset Access Code", which confirms first since it resets everyone's access), review and block accounts via "Linked Accounts…", and enable or disable remote access — no terminal required. The code is persisted in the app's user-data directory, survives app updates, and is removed only on a full uninstall.

Session code lifetime

Session codes are stable — a code is generated once at install and reused across reboots, service restarts, reconnects, and updates. It does not auto-rotate or expire on a timer. The code changes only when you run aicommander-agent change-code (Linux) or click "Reset Access Code" in the desktop tray, and it is removed only on a full uninstall. On Linux it is persisted under /etc/aicommander-agent/; the desktop app keeps it in its user-data directory. Run aicommander-agent status (Linux) or open the desktop app at any time to see the current code.

Connect a client — MCP, REST or Skill

AI Commander exposes one capability — run a command on a machine by its session code — through three interchangeable surfaces: a Model Context Protocol (MCP) server, a plain REST API, and an installable Agent Skill. They all hit the same relay and the same two operations (remote_exec / session_status). No login is needed to add the connector. Without a token, raw-code access works only during the code's first hour; signed-in access works any time after that. You drive machines by quoting their session code.

The MCP endpoint is https://aicommander.dev/mcp. Add it to Claude Code or another MCP-compatible client to make the remote_exec and session_status tools available — or skip MCP entirely and use the REST API or Agent Skill below.

Add it to your CLI agent

Pick your client — most connect over HTTP with a single command, no token:

Then mention a code in chat: "Run df -h on AIC-7K3P-WX9M-RTBN."

Coding GUIs, chat apps & everything else

Coding GUIs (Cursor, Windsurf, Antigravity) use a local stdio JSON config; chat apps (ChatGPT, Claude Desktop) add a custom HTTP connector; any MCP-compatible client can connect over HTTP+SSE with no auth header. Full per-client setup: Connect your AI client.

REST API & Agent Skill — no MCP needed

If your client doesn't speak MCP — or you just want a single HTTP call — the same two operations are a plain REST API. Auth is identical to MCP: without a token, requests are anonymous and work only during the code's first hour; Authorization: Bearer <api-key> gives alias-based access at any time.

# Run a command (buffered JSON result)
$ curl -s -X POST https://aicommander.dev/api/v1/exec \
    -H 'Content-Type: application/json' \
    -d '{"code":"AIC-7K3P-WX9M-RTBN","command":"df -h"}'

Send Accept: text/event-stream to stream instead of buffer. Machine-readable spec: /openapi.json. Any chat model with a fetch/browse tool can discover and call this on its own — see chat apps without MCP.

Agent Skill (Claude). Prefer a skill over an MCP server? Install the hosted SKILL.md into your skills directory — Claude auto-loads it and drives machines over the REST API, no claude mcp add:

$ mkdir -p ~/.claude/skills/aicommander && \
    curl -fsSL https://aicommander.dev/skill/SKILL.md -o ~/.claude/skills/aicommander/SKILL.md

Full guide: REST API & Skill.

Session Codes

Session codes are high-entropy identifiers that map an online agent to a relay session. Format: AIC-XXXX-XXXX-XXXX — three groups of 4 characters drawn from an unambiguous alphabet (no I, L, O, or U), giving ~59 bits of CSPRNG entropy. Example: AIC-7K3P-WX9M-RTBN. A code is generated once at install and stays stable across reboots and restarts.

How Claude uses them

Claude recognizes the AIC- prefix in conversation and can route commands to the right machine via remote_exec. You do not need per-machine MCP config; use the current code for the machine you want to reach.

Multiple machines

You can have any number of agents registered simultaneously. Each gets its own code and its own isolated session. A command sent to AIC-7K3P-WX9M-RTBN is routed only to that session, not to AIC-9F4D-2HQN-VK7T.

Sharing codes

A session code is sensitive — it is the credential for that machine. Anyone who knows a current code can run commands on it for as long as the code stays valid, so only share codes with people and agents you trust. To give someone ongoing access, just share the current code — they sign in (free) and stay connected indefinitely (though a first link made after the code's first hour starts blocked until the machine's operator approves it). To cut someone off you have two options: block just their account from the machine itself — aicommander-agent block-admin / unblock-admin or the desktop tray's "Linked Accounts…" (available at any time) — or reset the code (change-code), which is the master "start over" action: the old code stops working immediately and all links and blocks are cleared.

Desktop App

The desktop app is a lightweight menu bar application for macOS and Windows. It shows the current agent status, copies the current session code, resets the code ("Reset Access Code" — which confirms first, since it resets everyone's access), lists linked accounts and lets you block or unblock them via "Linked Accounts…" (masked emails; available at any time), and lets you enable or disable remote access with a single click. The code is persisted in the app's user-data directory, survives app updates, and is removed only on a full uninstall.

• Connected — agent is running and reachable
• Reconnecting — agent is trying to re-establish the WebSocket
• Disabled — access is paused; the agent will not accept commands

Download links are on the home page. Supports macOS (Apple Silicon + Intel) and Windows x64.

Security

The access model is simple: a session code is the credential for its machine. Anyone who knows a current code can run commands on that machine — for as long as the code stays valid — until the owner resets the code or blocks their account. The code is stable (it doesn't auto-rotate); it's minted/refreshed only when someone with physical/admin access installs the agent or runs change-code.

Who can use a code

• The code is the credential; sign in (free) for ongoing access. Connect with an account — a personal API key or magic-link OAuth — and on first use the machine auto-links to your account and is saved under an alias; you can then use the alias or the raw code interchangeably (subject to the daily key re-activation gate, which is about keeping the key itself active). When you first link matters: connect within the code's first hour (its trusted onboarding window) and your account is linked with access instantly and keeps it. Make that first connection after the first hour and your account is still linked but starts blocked — pending the machine operator's approval (the code may have leaked by then, so a new account needs explicit owner sign-off rather than self-service); it works only once the operator unblocks it via the tray's "Linked Accounts…" (or aicommander-agent unblock-admin). An account that already has access keeps it. Access lasts until the owner resets the code or blocks your account.
• No account needed for the first hour. During the first hour after a code is created or refreshed, anyone can paste the code and go — no account, no token ("anonymous" access). After that first hour, no-account access stops working and remote_exec / session_status tell the user to sign in (or have the owner reset the code).
• Giving someone access: just share the current code — they sign in (free) and stay connected. A signed-in account can also add a machine from the dashboard (POST /api/machines) with a code of any age.
• Blocking an account (owner-side): from the machine itself the owner can list who's linked and block or unblock one account — aicommander-agent list-admins / block-admin / unblock-admin, or the desktop tray's "Linked Accounts…". These use device-authenticated endpoints proven by the agent's on-disk device identity (deviceId + deviceSecret), and emails are masked server-side (e.g. lu****@wear****.com) — a full address never leaves the relay. Blocking refuses that account's access and stops it re-linking; the account stays listed (in a "Blocked" section) so you can unblock to restore it instantly. Available at any time. To remove everyone at once instead, reset the code (which clears all links and blocks).

Security FAQ

Do you log or store my commands and their output?

No — this is a guarantee, not best-effort. We never log or persist payloads. Commands and their stdout/stderr are never written to logs or any database; no command text or output is stored at all. Data is processed only transiently in the relay's memory while it streams through, then discarded. We keep no command history.

Is the connection encrypted?

Yes, in transit: every link (agent↔relay and client↔relay) runs over TLS to the edge. It is not end-to-end encrypted, though — the relay handles command text and output in plaintext in memory in order to forward it (and only for that — it is never stored). If you need the relay itself to never see plaintext, this isn't the right tool. We're deliberate about saying so.

And be honest with yourself about what end-to-end would even mean here: the moment you drive a remote machine through an AI tool — Claude, Codex, or any other AI client — that tool is one of the endpoints. It has to read your command output and write the next command in plaintext to do its job, and that plaintext lives on the AI provider's side too. So "no one but me ever sees the text" isn't achievable with this kind of workflow, no matter how the transport is encrypted. If that's a hard requirement, an AI-driven remote shell isn't the right fit.

What happens if my session code leaks?

The code is the credential, so treat it like an SSH private key. To lock everyone out instantly, reset it with change-code — the old code stops working immediately and all account links and blocks are cleared. (You can also block an individual account at any time.) Codes are also stored only in keyed (hashed) form, so a database leak never exposes them.

How do I see who has access to a machine, and remove someone?

From the machine itself: run aicommander-agent list-admins (or open the desktop tray's "Linked Accounts…") to see every account currently linked. Emails are masked (e.g. lu****@wear****.com) — the full address is never sent from the relay. To block one account, use aicommander-agent block-admin <number> (or the Block button in the tray window) — this works at any time, refuses that account's access, and stops it re-linking; the account stays listed in a "Blocked" section so unblock-admin (or the Unblock button) restores it instantly. To lock everyone out at once, reset the code (change-code / "Reset Access Code"), which clears all links and blocks.

I signed in and added a machine but it says "No access" — why?

You connected after the code's first hour. That first hour (after the code is created or reset) is a trusted onboarding window; connect within it and your account is linked with access instantly. After it, the code may have leaked, so for safety a brand-new account is linked but starts blocked until the machine's operator approves it. Ask them to open "Linked Accounts…" on the machine (or run aicommander-agent unblock-admin) and unblock your account — then the "No access" badge clears and it works.

What if my account API key leaks?

API keys are stored hashed and are revocable from the dashboard at any time. By default they're also gated by daily re-activation: a key stays dormant unless the owner has signed in through the web recently, so a key sitting in a file can't be used on its own indefinitely. A last used timestamp helps you spot unexpected use.

Are any risky features on by default?

No. Higher-reach capabilities are opt-in. Desktop screen sharing is off until you enable it in the tray, and the daily re-activation gate is on by default — you can turn it off, but the dashboard flags that as risk-increasing.

Can an AI agent be tricked into doing something via command output?

We mitigate this: the MCP tools instruct the model to treat all command output strictly as untrusted data to relay back to you, never as instructions to act on. Output is also size-capped so a flood can't destabilize the relay.

Does this open a port on my machine?

No. The agent only makes one outbound WebSocket connection to the relay. Nothing listens for inbound connections, so there's no port to scan, and it works behind NAT and firewalls without changes.

Can other people see my machines or output?

No. Each session is an isolated instance, and a command's output is routed only to the connection that issued it.

Is this a sandbox?

No — it's remote shell access. The agent runs as root by default for administration work; run it as a non-root user to restrict what commands can do. Anyone who knows a current code can run commands on that machine, so the security model is about controlling who holds the code (reset it to lock everyone out, or block an individual account).

Architecture

AI Commander has two parts: the hosted relay (the MCP/REST endpoint your AI client talks to) and a small agent on each machine you control. The agent dials out to the relay, so nothing listens for inbound connections on your machine.

How a command flows

1. The agent starts and opens an outbound, encrypted connection to the relay, registering under its session code.
2. You mention AIC-7K3P-WX9M-RTBN to Claude → Claude calls remote_exec("AIC-7K3P-WX9M-RTBN", "df -h").
3. The relay authenticates the request and routes it to the isolated session for that code.
4. The agent runs the command and streams stdout/stderr back through the relay as SSE events → Claude receives streaming output.
5. The process exits → the stream closes with the exit code and a final summary.