Connect your AI client

Wire up AI Commander, your AI command center for remote computer management, through MCP, plain REST, or an Agent Skill. Pick your client below, install the agent on a machine, then run shell commands by quoting its machine code.

Before you start

The relay is already live at https://aicommander.dev/mcp. There is nothing to deploy or host. Connecting runs a one-time browser sign-in and binds the connector to your account (so saved-machine aliases resolve); for the quick no-account path, drive a machine by its code with https://aicommander.dev/mcp?anonymous=1. To use it, you need one thing:

1. An agent running on the machine you want to control, showing a session code like AIC-7K3P-WX9M-RTBN. Install it below.

You drive a machine by quoting its session code in chat. The code is the credential: anyone who knows a current code can run commands until the owner resets the code or blocks their account. New codes work without an account for the first hour; sign in for ongoing access. See Security.

Install the agent

Run the agent on the machine you want to control. Pick your platform — the download or install command updates below.

$ bash <<'AICOMMANDER_VERIFY'
set -euo pipefail
base="https://aicommander.dev"
expected_key_sha256="2d76d381fc8ed38e7dfb53882e14b2980ee105e0b49ff31cf55403e19e648407"

command -v curl >/dev/null || { echo "curl is required" >&2; exit 1; }
command -v openssl >/dev/null || { echo "OpenSSL 3.x is required" >&2; exit 1; }
case "$(openssl version 2>/dev/null)" in *LibreSSL*) echo "LibreSSL cannot verify this signature" >&2; exit 1;; esac
openssl_help="$(openssl pkeyutl -help 2>&1 || true)"
[[ "$openssl_help" == *"-rawin"* ]] || { echo "OpenSSL pkeyutl -rawin is required" >&2; exit 1; }

tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
metadata="$(curl -fsS --proto '=https' --tlsv1.2 "$base/dist/latest")"
version="$(printf '%s' "$metadata" | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([0-9][0-9.]*\)".*/\1/p')"
[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Invalid release version" >&2; exit 1; }

curl -fsS --proto '=https' --tlsv1.2 "$base/dist/v/$version/install" -o "$tmp/install"
curl -fsS --proto '=https' --tlsv1.2 "$base/dist/v/$version/install.sig" -o "$tmp/install.sig"
curl -fsS --proto '=https' --tlsv1.2 "$base/install.pub" -o "$tmp/install.pub"
[[ -s "$tmp/install" && -s "$tmp/install.sig" && -s "$tmp/install.pub" ]]

actual_key_sha256="$(openssl pkey -pubin -in "$tmp/install.pub" -outform DER 2>/dev/null | openssl dgst -sha256 | awk '{print $NF}')"
[[ "$actual_key_sha256" == "$expected_key_sha256" ]] || { echo "Signing-key fingerprint mismatch" >&2; exit 1; }
openssl pkeyutl -verify -pubin -inkey "$tmp/install.pub" -rawin \
  -in "$tmp/install" -sigfile "$tmp/install.sig" >/dev/null \
  || { echo "Installer signature verification failed" >&2; exit 1; }

sudo bash "$tmp/install"
AICOMMANDER_VERIFY

Full technical details and the session-code lifetime: The Linux agent.

Pick your client

Choose the setup that matches the tool you already use:

CLI agents

Terminal coding agents. Most connect to the remote relay over HTTP with one command. The first use runs a one-time browser sign-in and binds the connector to your account; append ?anonymous=1 to the URL for the quick no-sign-in path (drive a machine by its code).

[mcp_servers.aicommander]
command = "npx"
args = ["-y", "@aicommander/mcp"]
env = { AICOMMANDER_SERVER = "https://aicommander.dev" }

Coding GUIs & IDEs

Editors and AI coding tools — Cursor, Windsurf, Antigravity, Zed, and others — accept an MCP server as JSON and run it locally over the same stdio bridge. The config is identical everywhere; only the file location differs:

{
  "mcpServers": {
    "aicommander": {
      "command": "npx",
      "args": ["-y", "@aicommander/mcp"],
      "env": {
        "AICOMMANDER_SERVER": "https://aicommander.dev"
      }
    }
  }
}

• Cursor — ~/.cursor/mcp.json (or Settings → MCP → Add server).
• Windsurf — ~/.codeium/windsurf/mcp_config.json (or Settings → Cascade → MCP servers).
• Antigravity — add the server in Settings → MCP / Tools; paste the same JSON when it asks for a server definition.
• Any other IDE — wherever it stores its MCP server list, use the same three keys (command, args, env).

On Windows use "command": "npx.cmd". Add "AICOMMANDER_TOKEN": "<your-key>" to env for alias-based access. Restart the editor; the remote_exec and session_status tools appear.

Chat apps — ChatGPT & Claude (MCP connectors)

The desktop / web chat apps connect to the relay as a custom connector — a remote HTTPS MCP endpoint. Adding the connector runs a one-time browser sign-in and binds it to your account (so saved-machine aliases resolve); the client auto-registers, so no manual credentials are needed. For the quick no-sign-in path, point it at https://aicommander.dev/mcp?anonymous=1 instead. A confidential OAuth client (Client ID + Client Secret) is an optional way to authenticate — see Optional: pre-provisioned OAuth credentials below.

ChatGPT

Settings → Connectors → Advanced / Developer mode → Add custom connector:

• URL: https://aicommander.dev/mcp
• Auth: leave it empty — the connector auto-registers and you complete a one-time browser sign-in that binds it to your account. (For a client that needs pre-provisioned credentials, paste a Client ID + Client Secret instead; see below. For the anonymous-by-code path, use https://aicommander.dev/mcp?anonymous=1 as the URL.)

Claude Desktop

Custom connector (recommended): Settings → Connectors → Add custom connector, URL https://aicommander.dev/mcp, leave auth empty — the connector auto-registers and you complete a one-time browser sign-in that binds it to your account. (For the anonymous-by-code path use https://aicommander.dev/mcp?anonymous=1; for a client that needs pre-provisioned credentials, paste a Client ID + Client Secret — see below.) Or use the stdio config file claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/) with the same JSON as the IDE config above, then restart Claude Desktop.

Optional: pre-provisioned OAuth credentials (Client ID + Secret)

Account binding is the default at https://aicommander.dev/mcp: just point the connector there and complete the one-time browser sign-in — the client auto-registers (Dynamic Client Registration), so most clients need no manual credentials. You only need a confidential OAuth client — a Client ID and a one-time Client Secret — for clients that require pre-provisioned credentials and can't self-register. You still complete the normal browser sign-in when you connect, and that interactive login is what decides which account the connector's access is bound to.

1. In the dashboard, go to OAuth clients and create a client. For the Redirect URI, Claude (Desktop, web, mobile) uses the fixed callback https://claude.ai/api/mcp/auth_callback (pre-filled); Claude Code uses a local loopback, so add http://localhost/callback and http://127.0.0.1/callback. You get a Client ID and a one-time Client Secret.
2. Point the connector at https://aicommander.dev/mcp and, in its Auth / advanced settings, paste the client_id and client_secret.
3. Connect — Claude opens a browser sign-in; completing it binds the connector to your account.

Chat apps without MCP

No connector support, or don't want to set one up? Any capable chat model — the ChatGPT app, the Claude app, or similar — can drive a machine if it can make HTTP requests through browsing, code interpreter, or a generic fetch tool. There is no config to paste; give it the relay, the machine code, and the goal.

Give it the relay, the machine's code, and the goal. For example:

# Paste this into ChatGPT / Claude (with web or tool access enabled)
Connect to my computer AIC-7K3P-WX9M-RTBN through aicommander.dev
and tell me its disk usage.

The REST API is documented at https://aicommander.dev/openapi.json
(POST https://aicommander.dev/api/v1/exec with JSON {"code","command"}).
No auth is needed for the first hour after a code is created or refreshed;
sign in (free) to use the code at any time after that.

The model can then call /api/v1/exec with the code and a command like df -h, read the JSON result, and answer. You can keep going in plain language ("now restart nginx", "tail the last 50 lines of the app log") and it will make new calls as needed.

Any MCP client (raw HTTP+SSE)

The relay speaks standard MCP over HTTP with SSE responses. Point any compliant client at:

# Endpoint — no auth header needed
POST https://aicommander.dev/mcp
Accept: text/event-stream

Tools exposed: remote_exec(code, command, cwd?, timeout_ms?), session_status(code), and (with an API key) list_machines() to list every machine on your account with its live online status. Streaming command output arrives as SSE message events.

REST API & Agent Skill (no MCP needed)

If your client doesn't speak MCP — or you want a single HTTP call — use the REST API. Auth matches MCP: no token means anonymous access during a code's first hour, while Authorization: Bearer <api-key> enables alias-based access after sign-in. There is no OAuth browser flow on this surface; REST clients paste an API key.

# Is the machine online?
$ curl -s https://aicommander.dev/api/v1/status/AIC-7K3P-WX9M-RTBN

# 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"}'

The exec response is { "ok": true, "exitCode": 0, "stdout": "…", "stderr": "…", "truncated": false }. Add "cwd" and "timeout_ms" as needed, or send Accept: text/event-stream to stream the result instead of buffering. Machine-readable spec: /openapi.json.

Install the Agent Skill (instead of the MCP server)

SKILL.md is an open Agent Skills format supported by Claude Code and other agents. If you prefer a skill over an MCP server, install the hosted AI Commander skill into your agent's skills directory. It is served from the relay, so there is nothing to clone. The example below uses Claude's ~/.claude/skills/ location; point it at your agent's skills folder if it differs:

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

Your agent auto-loads it on the next session — quote an AIC-… code and it drives the machine over the REST API, with no MCP server to add and no OAuth. View the skill: /skill/SKILL.md.

Accounts & API keys

You can try a fresh machine code without an account for the first hour. For ongoing access, sign in with a passkey or email magic link — no password. An account lets you:

• Save machines under friendly aliases (e.g. prod-db instead of AIC-7K3P-WX9M-RTBN). After a machine is linked, use the alias or the raw code while the owner allows access.
• Generate or revoke a personal API key in the dashboard and set it as the Bearer token in any MCP client — then reach all your linked machines by alias.

With an API key set (Authorization: Bearer <key>, or AICOMMANDER_TOKEN=<key> for the @aicommander/mcp stdio bridge), remote_exec and session_status accept either a raw AIC-… code or one of your aliases.

Owner controls — who can reach your machine

The machine's owner stays in charge of access at all times:

• Block or unblock a specific account — at any time. From the CLI, aicommander-agent block-admin <n> and aicommander-agent unblock-admin <n>; from the desktop tray, Linked Accounts…. Blocking refuses that account's access and stops it re-linking; the account stays listed in a Blocked section, and unblocking restores access instantly.
• Reset the code — aicommander-agent change-code or Reset Access Code in the desktop app. This mints a brand-new code; the old code dies immediately and all links and blocks are cleared. It's the master "lock everyone out / start over" action.

Service tokens — for automation

remote_exec and /api/v1/exec give an AI root-level, interactive access — great when you're driving the machine yourself. For unattended work — a cron job, a CI step, or one AI agent calling another with claude -p — there's a deliberately narrower lane: secure exec, driven by a service token. It's the opposite of the root path: a non-root sandbox, pinned to one machine, limited to an allowlist of commands.

• Non-root, checked every time. Commands run as a dedicated aicommander-exec user, not root. The agent refuses privileged primary/supplementary groups and any unreadable or ambiguous local account/group data before spawn.
• Allowlisted, no shell, known runners denied. You send an argv vector and the exact command basenames you permit. There's no shell, so &&, ; and $(…) are inert text. The Worker and agent also refuse known shells/runtimes (sh, bash, python*, node, etc.), argument runners (env, find, xargs, awk, sed, etc.), privilege tools and container/orchestration clients (sudo, docker, kubectl, etc.).
• Pinned & long-lived. A token works on exactly one machine, never expires, and skips the 24h dashboard re-activation gate — so automation keeps running. Revoke it anytime.
• Audited without payloads. Each run logs the command basename, exit code, duration, caller IP and byte counts — never your arguments, input, or output.

Create a token in the dashboard (Service tokens → pick a machine → choose allowed commands) — the plaintext token (aics_…) is shown once. Then call the secure-exec endpoint:

# Run an allowlisted command, non-root, on the pinned machine
$ curl -s -X POST https://aicommander.dev/api/v1/secure-exec \
    -H 'Authorization: Bearer aics_…' \
    -H 'Content-Type: application/json' \
    -d '{"argv":["df","-h"]}'

The response mirrors /api/v1/exec ({ "ok": true, "exitCode": 0, "stdout": "…", "stderr": "…", "truncated": false }, output capped at 8 MiB; add a base64 "input" for stdin, plus optional "cwd" / "timeout_ms"). Only a service token is accepted here — an account API key, admin token, or anonymous request is rejected. Create tokens in the dashboard; list/revoke them via /api/v1/secure-tokens and view recent runs via /api/v1/secure-exec/audit; full reference in the API docs.