Connect your AI client

Keep using your own AI client — we provide the host agent and MCP connector. Install the agent on your machine, connect your AI client, then run commands or long-running jobs using the machine code.

Setup instructions for AI agents · Concise index

Before you start

Install on the machine you want to control. Its code is the credential: anyone who knows a current code can run commands until you reset it or block their account. Anonymous access works for a new code's first hour; sign in for ongoing access. Access and security.

Pick your client

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.

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

[mcp_servers.aicommander]
url = "https://aicommander.dev/mcp"

extensions:
  aicommander:
    enabled: true
    type: streamable_http
    name: aicommander
    description: Remote machines via AI Commander
    uri: "https://aicommander.dev/mcp"
    timeout: 300

"amp.mcpServers": {
  "aicommander": {
    "url": "https://aicommander.dev/mcp"
  }
}

"mcp": {
  "aicommander": {
    "type": "remote",
    "url": "https://aicommander.dev/mcp",
    "enabled": true
  }
}

{
  "mcpServers": {
    "aicommander": {
      "url": "https://aicommander.dev/mcp",
      "auth": "oauth"
    }
  }
}

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

# 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.

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

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

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

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

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

Long-running jobs

A training run, a long build, or an overnight dataset job shouldn't need a session kept alive. Start it as a detached job: the call returns a jobId straight away and the work keeps running on your machine after the chat ends and after your client disconnects. No tmux, no screen, nothing to keep open. A job also outlives the agent itself restarting on all three platforms; on Linux each job started by an agent that already has this feature is launched into its own transient systemd scope, outside the agent service's control group, so stopping or restarting the service — an agent upgrade included — leaves it running, provided the box runs systemd and the agent runs as root. Without both, jobs stay in the service's control group and a restart still ends them, and a job that was already running when the agent was upgraded to that version is in no scope either, so the upgrade's own restart ends it. See Start ML training on your own GPU for the full walkthrough.

From an MCP client — just ask

Five tools cover the whole lifecycle. In practice you phrase it in plain language and the client picks the tool:

• Start it — “on gpu-box, start ./.venv/bin/python train.py in /home/u/aic-jobs/mytrain on GPU 0 as a job called mytrain” → remote_job_start(code, command, cwd?, env?, name?, gpu_index?), which answers with the jobId. cwd must be an absolute path that already exists, and env takes string values only.
• See what's running — “what jobs are running on gpu-box?” → remote_job_list(code, status?, include_command?).
• Check on it — “how did mytrain go?” → remote_job_status(code, job_id, include_command?), which reports running, exited with the exit code, or unknown (the process is gone and no exit code was recorded — after an agent restart, a SIGKILL, an OOM kill, or a cancellation that had to escalate — so the outcome genuinely can't be determined).
• Read the log — “show me the last 200 lines of mytrain” → remote_job_logs(code, job_id, tail_lines?, offset_bytes?, max_bytes?). Stdout and stderr are interleaved, the last 200 lines by default. Each reply is capped at 256 KiB and carries a nextOffsetBytes; feed that back as offset_bytes to follow a growing log instead of re-reading it.
• Stop it — “cancel mytrain” → remote_job_cancel(code, job_id), which kills the whole process tree and releases any reserved GPU.

Passing gpu_index reserves that NVIDIA card for the job, so a second run asking for the same card is refused (gpu_busy, naming the holder) rather than both runs hitting CUDA OOM. On agents 1.0.50 and newer, when the machine's GPU list is known, an index that is not on it is refused with invalid_request rather than starting a phantom job; an older agent takes any in-range index and lets the job fail inside CUDA. Jobs have no elevated option.

Over REST

Same operations, same authorization as /api/v1/exec. code goes in the JSON body for the POST and as a query parameter everywhere else:

# Start a job — returns the jobId immediately
$ curl -s -X POST https://aicommander.dev/api/v1/jobs \
    -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
    -d '{"code":"gpu-box","command":"./.venv/bin/python train.py","cwd":"/home/u/aic-jobs/mytrain","name":"mytrain","gpu_index":0}'

# → {"ok":true,"job":{"jobId":"9f2c1b7ad4e05386","name":"mytrain","status":"running","exitCode":null,"gpuIndex":0,"logBytes":0,"truncated":false, …}}

# List jobs on the machine
$ curl -s 'https://aicommander.dev/api/v1/jobs?code=gpu-box'                       -H 'Authorization: Bearer YOUR_API_KEY'

# Poll one job's status
$ curl -s 'https://aicommander.dev/api/v1/jobs/9f2c1b7ad4e05386?code=gpu-box'      -H 'Authorization: Bearer YOUR_API_KEY'

# Tail the log, then follow it with offset_bytes=<nextOffsetBytes>
$ curl -s 'https://aicommander.dev/api/v1/jobs/9f2c1b7ad4e05386/logs?code=gpu-box&tail_lines=200' -H 'Authorization: Bearer YOUR_API_KEY'
$ curl -s 'https://aicommander.dev/api/v1/jobs/9f2c1b7ad4e05386/logs?code=gpu-box&offset_bytes=131072' -H 'Authorization: Bearer YOUR_API_KEY'

# Cancel it
$ curl -s -X DELETE 'https://aicommander.dev/api/v1/jobs/9f2c1b7ad4e05386?code=gpu-box' -H 'Authorization: Bearer YOUR_API_KEY'

A log reply is { "ok": true, "logs": { "chunk": "<base64>", "offsetBytes": …, "nextOffsetBytes": …, "eof": …, "truncated": … } } — chunk is base64 because process output is arbitrary bytes. eof: true means you've read to the current end of the file, not that the job finished. Machine-side refusals get their own status: 409 gpu_busy, 429 too_many_jobs, 404 not_found, 400 invalid_request. Full reference: Docs → Detached jobs.

To get a checkpoint or a render off the machine, use POST /api/v1/pull — it returns a download link, and access to the stored copy ends after 24 hours. An hourly, retrying sweep removes inaccessible expired bytes afterward. Above its 100 MiB limit, have the job push the artifact to storage you already control (aws s3 cp, rclone, scp) as its final step.

Accounts & API keys

The hosted relay is https://aicommander.dev/mcp; there is nothing to deploy. HTTP connections run a one-time browser sign-in and bind the connector to your account so saved-machine aliases resolve. For the no-account path, use https://aicommander.dev/mcp?anonymous=1 and a machine's code during its first hour.

Remote HTTP clients include Claude Code, Grok, Gemini CLI, opencode, Qwen Code, Codex, ChatGPT and Claude Desktop connectors. Local stdio clients use @aicommander/mcp: pi, Cursor, Continue, Windsurf, Antigravity and Claude Desktop's config file.

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.