AgentPort

Version 3.1 remote development gateway for MCP, CLI, SSH recovery, durable Jobs, Git Worktree sessions, and named workspace isolation.

Job Admission Groups

Daemon Jobs optionally use light, heavy and service group caps while retaining a strict global concurrency limit. Untagged/legacy custom classes count as heavy. Enable caps with JOB_CLASS_LIMITS_JSON; for example, on a suitably provisioned host, JOB_MAX_CONCURRENCY=4 and JOB_CLASS_LIMITS_JSON={"light":2,"heavy":2,"service":1}. This is not a recommended change for a memory/swap-pressured host. Defaults remain 2 global Jobs, 15 seconds of admission waiting, and at most 32 pending requests (JOB_MAX_PENDING). A blocked group does not block eligible groups; each group remains FIFO. All groups, including long-lived services, count globally.

CLI job start/safe-job accept --resource-class and --queue-timeout-ms; MCP async tools accept resourceClass and queueTimeoutMs. Group labels are not CPU/memory isolation, and must not be used to disguise heavy work as light. service does not install systemd units, disable timeouts, or enable restart. Change live policy only after pending submissions drain. Pending HTTP requests are bounded, not durable accepted Jobs; only a returned handle proves admission. Capacity failures retain HTTP 429 / EJOB_QUEUE / accepted:false and diagnostic group/queue details. Do not bypass them with SSH or auto-replay UNKNOWN work.

Enable AI Agents to develop on remote Linux servers through the most stable available channel: native MCP tools, CLI fallback, daemon HTTP APIs, SSH recovery, and persistent remote jobs.

中文文档

One-line Summary

Give AI Agents a stable remote development gateway: direct file operations, command execution, diagnostics, long-running job control, and recovery paths when a desktop tool's native MCP transport is unavailable or unstable.

Analogy: VS Code Remote SSH is for humans; agentport is for AI.

Related MCP server: SSH MCP Server

Architecture Overview

AgentPort has a local client side and a remote Linux daemon side. One daemon can serve many AI desktop applications; every application keeps its own local configuration and credential material.

AI desktop tool
  -> native MCP (short structured work) / CLI fallback / SSH recovery
  -> local client runtime and private local/ configuration
  -> public development gateway (default port 3183)
       -> development-session API
       -> modular file, search, exec, and Job services
       -> loopback legacy dashboard and management compatibility service
  -> explicitly configured remote workspace roots

The local client registers MCP tools when available, provides a CLI fallback, reads only private connection configuration, and turns daemon errors into agent-readable messages. The remote daemon performs token authentication, path checks, file operations, command execution, durable Job control, Worktree sessions, audit logging, health checks, Dashboard responses, and configuration reload.

For desktop tools that spawn multiple MCP stdio children per software, agentport now keeps one local "core" process per software key and lets other sessions attach through a localhost proxy broker. This reduces duplicate connection churn without forcing single-session usage.

Remote setup safety policy:

• remote_setup defaults to client-only mode (deploy=false).

• Existing remote daemon files are not overwritten by default.

• Overwrite requires explicit deploy=true and forceDeploy=true.

• For existing servers, use node cli.js client provision to create or reuse one token for the current machine/software. Do not ask agents to print or manually copy raw AUTH_TOKENS values.

• For first-time server bootstrap, run read-only detection first, then deploy once from one operator computer, then provision each other client separately.

• For multi-computer usage, do not share one token. Create one unique clientId=token per computer/software.

For design rationale, deployment model, and security boundaries, see the project documentation in this repository.

Core Features

Named Workspaces

Version 3.1 can expose more than one remote root without granting the daemon access to the rest of the server. Each root has a stable name and roots must not overlap.

{
  "default": "projects",
  "roots": {
    "projects": "/home/YOUR_USER/workspace",
    "openclaw": "/home/YOUR_USER/.openclaw"
  }
}

Save this as workspaces.json beside the daemon environment file, then set:

WORKSPACE_ROOT=/home/YOUR_USER/workspace
DEFAULT_WORKSPACE=projects
WORKSPACE_ROOTS_FILE=./workspaces.json

The daemon accepts all of these forms:

File, search, command, Job, and development-session operations all retain this workspace scope. Paths outside every configured root, .. traversal, and symlinks escaping a root are rejected with EWORKSPACE.

This is a daemon/MCP boundary. A person or an agent using direct SSH still has the Linux account permissions granted to that SSH connection.

Remote Search Dependencies

remote_grep does not require ripgrep: daemon mode uses bounded Node-based search and SSH recovery uses bounded grep. For agents that run direct shell searches, install the optional ripgrep package to provide rg:

sudo apt update
sudo apt install -y ripgrep
command -v rg

node cli.js doctor reports whether rg is available for each SSH connection. When it is missing, agents should feature-detect it and fall back silently to a project-scoped grep search rather than running a known-missing command.

Agent Integration Priority

agentport is a remote development gateway with multiple runtime channels. Choose by task type:

1. Native MCP for short structured operations: if remote_* tools are healthy, use them for a windowless local workflow.

2. CLI daemon gateway for long-running development: use safe-job and persistent job commands for tests, builds, installs, polling, and logs.

3. SSH-first CLI as the recovery path: use --route ssh when native MCP or daemon transport is unavailable. Synchronous commands time out by default.

4. HTTP/manual last: only use direct REST calls or manual commands when SSH, daemon, and native MCP are all unavailable.

CLI fallback examples:

node cli.js doctor
node cli.js list
node cli.js connect <connection-name>
node cli.js health
node cli.js ssh-health
node cli.js health --route ssh
node cli.js read projects:/AGENTS.md --connection <daemon> --route daemon
node cli.js glob "**/*.js" --cwd openclaw:/software/app --connection <daemon> --route daemon
node cli.js bash "pwd && ls -la" --cwd projects:/app --connection <daemon> --route daemon
node cli.js bash "pwd && ls -la" --cwd /path/to/workspace --connection <ssh> --route ssh --json
node cli.js safe-bash local-readonly-check.sh --cwd /path/to/workspace --connection <ssh> --route ssh --plain
node cli.js write projects:/tmp.txt --content "hello" --connection <daemon> --route daemon

safe-bash and safe-script return JSON by default. Their optional --plain mode writes script stdout/stderr to the matching local streams and returns a nonzero process status when the remote script fails. Do not retry merely because a successful script produced no output. In Git Bash on Windows, MSYS may rewrite positional remote targets for read, write, and safe-write, as well as --cwd and --remote-tmp-dir, before Node starts; quoting alone is not reliable. Prefer PowerShell. If Git Bash is required, use MSYS2_ARG_CONV_EXCL='*' and Windows-compatible local file/script paths (cygpath -w when needed). Do not repair already converted paths. The CLI rejects recognizable converted Windows paths for remote file targets and directory arguments.

The optional READ_ONLY_RULE_FILES_JSON server setting is disabled by default. When explicitly enabled by an administrator on the modular daemon, it allows authenticated normal file-read and batch-read access to registered exact text files up to 256 KiB. It grants no stat, byte-read, search, write, cwd, or arbitrary command access. Health-reported roots and boundary fields are not an independent security test; path checks are not an OS sandbox. This client documentation does not imply that a server has enabled the setting.

Local MCP broker failures no longer cause unconditional replay. A replacement broker may be loaded after a confirmed unsent request; ambiguous commands, writes, and Job submissions return EOUTCOME_UNKNOWN. Reconcile the original handle/state before retrying. Permission denials never trigger route fallback. Execution errors use MCP isError, and compact terminal logs distinguish completed, failed, and unknown outcomes. Credential fields are redacted before log truncation; old log files are not rewritten by this update.

Run the isolated recovery and logging regressions with npm run test:mcp:recovery.

Inspect recent local MCP activity without connecting to a server:

node cli.js diagnostics --days 7
node cli.js diagnostics --log-dir <skill-dir>/local/logs --days 7 --max-mb 64 --json

The report contains aggregate counts, error categories, and latency. Correlated proxy/owner records are deduplicated; older records without complete metadata are counted separately. It never prints raw arguments, command output, paths, client IDs, or tokens. Scans are bounded (32 MiB and 64 files by default), and partial coverage is explicit. Missing completion records are not proof of failed or still-running work. These are MCP observations, not a daemon availability or business success rate. --days accepts 1-90 and --max-mb accepts 1-256.

New log messages are capped at 1024 UTF-8 bytes. Data remains valid JSON within MCP_REMOTE_LOG_DATA_MAX_BYTES (default 4000), with _truncated metadata when needed. Failure logs retain call identity, category and state instead of full stdout/stderr and repeated history snapshots. Tool responses still contain their normal output. Healthy proxy startup is informational. Run npm run test:diagnostics for isolated report tests. The update does not rewrite old logs.

Daemon grep validates regular expressions before sending a search request. Use JavaScript syntax and caseSensitive: false instead of (?i); CLI searches are case-insensitive unless --case-sensitive is supplied. Literal search remains the default. SSH grep keeps its existing native grep syntax.

Provision a daemon token for a new AI software or new computer:

# First make sure an SSH connection to the server exists in local/connections.json.
node cli.js ssh-health --connection <ssh-connection> --route ssh --json

# Create or reuse a unique token, write it to the remote daemon config, and
# store only this software's daemon connection in its own local/connections.json.
node cli.js client provision \
  --client-id <machine-software> \
  --connection <admin-daemon-connection> \
  --route daemon \
  --daemon-name <machine-software-daemon> \
  --local-dir <skill-dir> \
  --json

If the current daemon does not yet support raw admin config reads, run the same command with --route ssh --connection <ssh-connection>, then reload or restart the daemon before validating the newly created token. The command only prints a masked token.

For long-running development tasks, use the persistent daemon job gateway:

node cli.js status
node cli.js job start "npm test" --cwd /path/to/workspace
node cli.js safe-job local-build.sh --cwd /path/to/workspace --job-timeout-ms 1800000
node cli.js job status <job-id>
node cli.js job logs <job-id> --tail 200
node cli.js job cancel <job-id>
node cli.js job list --limit 20

The job gateway is designed for AI tools whose native MCP stdio transport may disconnect during long work. Jobs continue inside the remote daemon, and the AI can reconnect through the CLI to inspect status and logs.

When daemon transport is unhealthy, use lightweight SSH jobs as a recovery path:

node cli.js job start "sleep 30" --route ssh
node cli.js job status <job-id> --route ssh
node cli.js job logs <job-id> --route ssh --json
node cli.js job cancel <job-id> --route ssh

For shared-link disconnect diagnostics, use the built-in SSH trace tool:

node cli.js trace start ssh-link --route ssh --interval 2
node cli.js trace status ssh-link --route ssh --json
node cli.js trace logs ssh-link --route ssh --tail 120
node cli.js trace stop ssh-link --route ssh

Trace logs are written on the remote host under ~/.agentport/trace/<name>.log.

See AGENT_GUIDE.md for the full install and agent bootstrap workflow.

Execution Backpressure

The remote daemon protects itself with an execution slot queue:

When all execution slots are busy, new command requests wait in a queue. If the queue wait exceeds EXEC_QUEUE_TIMEOUT_MS, the daemon returns HTTP 429 with the current exec state:

{
  "error": "Too many concurrent exec operations",
  "exec": {
    "running": 4,
    "max": 4,
    "queued": 1,
    "timeoutMs": 120000,
    "queueTimeoutMs": 15000
  }
}

remote_health also reports this exec state, which helps distinguish service disconnects from an overloaded execution queue.

Quick Start

Fresh Agent Install Against An Existing Daemon

Use this path when a new AI software installs AgentPort for an already running remote daemon.

1. Clone Into This Software's Skill Directory

git clone https://github.com/knownothing20/agentport.git
cd agentport
npm install

Each AI software should have its own physical AgentPort directory. Do not use a junction when different tools need different credentials.

2. Create SSH-Only Local Config

Create local/connections.json from the example and fill in only SSH first:

cp local/connections.json.example local/connections.json

Example:

{
  "connections": [
    {
      "name": "ssh-main",
      "type": "ssh",
      "host": "192.0.2.10",
      "port": 22,
      "username": "leon",
      "privateKey": "~/.ssh/id_rsa"
    }
  ],
  "default": "ssh-main"
}

Verify the SSH baseline:

node cli.js ssh-health --connection ssh-main --route ssh --json

3. Provision This Software's Daemon Token

If this fresh install does not already have an admin daemon connection, use SSH provisioning:

node cli.js client provision \
  --client-id <machine-software> \
  --connection ssh-main \
  --route ssh \
  --daemon-url http://192.0.2.10:3183 \
  --daemon-name daemon-main \
  --local-dir . \
  --json

If the remote daemon was not hot-reloaded by the command, reload or restart it, then run the same provision command again. A successful result reports verification.ok: true and prints only tokenMasked.

Validate with an authenticated endpoint:

node cli.js job list --connection daemon-main --route daemon --limit 1 --json

4. Register Native MCP If Needed

If the target AI tool supports MCP servers, create local/agentport.json, set skillDir and mcpConfigPath, then run:

cp agentport.example.json local/agentport.json
node sync.cjs

Restart the AI tool after MCP registration changes.

Install on another computer or AI software

For a new computer or another AI desktop tool, use the same SSH-first flow. See INSTALL_OTHER_MACHINE.md.

CLI Guided Setup

The interactive wizard can help create SSH connections, but the non-interactive SSH-first flow above is the recommended path for agents:

npm run setup

Deploy or upgrade the remote daemon

Only one operator should deploy a daemon. Normal client installation must not overwrite an existing server. For 3.1, deploy the complete release together: daemon/, packages/daemon-core/, server/, and the root package files. Copying only server/ keeps the legacy daemon working but does not provide the modular file, Job, or development-session services.

On the remote server, install dependencies for both package roots and start the public development gateway:

cd /opt/agentport
npm ci
npm --prefix server ci
npm run start:daemon

Before activating an upgrade, validate the release in a separate directory. Keep the prior release available for rollback, update the service's release pointer, restart the service, then verify GET /healthz and an authenticated node cli.js health --route daemon --json call. Do not copy a real .env or a token into source control; keep them in the daemon's private configuration directory.

Supported AI Tools

Tool List

For detailed usage, see SKILL.md

Directory Structure

agentport/
|-- client/                         # Local MCP and CLI entrypoints
|-- daemon/                         # Public gateway and daemon configuration loader
|-- packages/
|   |-- client-core/                 # Connection, project, and Session client runtime
|   |-- client-transport/            # Daemon HTTP and lazy SSH transport
|   |-- daemon-core/                 # Path guards, file, exec, Job, and Session services
|   `-- shared/                      # Shared safety and request-context policies
|-- server/                          # Legacy dashboard and management compatibility service
|-- local/                           # Ignored private client configuration and logs
|-- docs/                            # Architecture and development-session documentation
|-- SKILL.md                         # Short runtime contract for AI agents
|-- AGENT_GUIDE.md                   # Install and usage guide
|-- cli.js / index.js                # Legacy-compatible CLI and MCP entrypoints
|-- sync.cjs                         # Skill and MCP configuration synchronizer
|-- test/                            # Cross-platform regression tests and test guide
`-- CHANGELOG.md                     # Version history

Configuration Files

See local/config-guide.md for detailed configuration guide.

Dashboard

agentport provides a Web Dashboard for monitoring and management:

Enable Dashboard

Set in local/agentport.json:

{
  "variables": {
    "serverEnableDashboard": "true"
  }
}

Access Dashboard

After starting the service, visit:

• http://your-server:3183/?token=<admin-token>

• http://your-server:3183/dashboard?token=<admin-token>

Dashboard uses admin auth. If this software needs Dashboard access, provision or promote its token with client provision --admin instead of editing remote .env by hand.

Dashboard Features

Autostart Configuration

For a 3.1 daemon, use a user-level systemd unit. It keeps the public gateway under the account that owns the workspace and avoids duplicate manager scripts.

Create ~/.config/systemd/user/agentport.service:

[Unit]
Description=AgentPort development gateway
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/agentport
Environment=AGENTPORT_ENV_PATH=/home/YOUR_USER/.agentport/daemon/.env
ExecStart=/usr/bin/node /opt/agentport/daemon/server-entry.cjs
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Load, enable, and inspect it:

systemctl --user daemon-reload
systemctl --user enable --now agentport.service
systemctl --user status agentport.service
curl -fsS http://127.0.0.1:3183/healthz

Do not run multiple copies of node server.js or multiple manager scripts for the same port. The legacy server/agentport-manager.sh remains for older single-process deployments only.

Security Features

• Named workspace isolation: File, search, exec, Job, and Session paths are restricted to configured non-overlapping roots.

• Traversal and symlink protection: .. traversal and symlinks escaping an authorized root are rejected.

• Token separation: Use one clientId=token per machine and AI software; keep tokens only in ignored local configuration or private daemon .env.

• Command policy: Shell metacharacter policy, interpreter restrictions, execution limits, queue limits, and process-tree cleanup protect execution.

• Explicit destructive actions: Session merge, rollback, cleanup, and branch deletion require explicit Session ID confirmation.

• Audit and redaction: Audit logs are stored remotely and API responses mask sensitive command and token material.

Version History

See CHANGELOG.md

License

MIT License - See LICENSE

Contributing

Issues and Pull Requests are welcome!

Enable the repository-local privacy hooks once:

git config core.hooksPath .githooks
npm run privacy:check
npm run privacy:release
npm run test:privacy

Use your verified GitHub noreply commit identity. Pre-commit checks the staged snapshot and identity; pre-push checks outgoing commits, including intermediate versions. Never bypass these hooks. Skill synchronization copies only tracked source and preserves each installation's private configuration. These local guards do not remove already published history or replace server-side policy.

Use privacy:release before publishing: it checks working files, staged bytes, author identities, and the complete history reachable from HEAD and local tags. Tag descriptions and Co-authored-by emails receive the same checks. Findings show file/object labels and rule names only; detected secrets are not printed. Git file blobs are read in batches; duplicate objects in each batch are scanned once. New branches are checked from their root; stale local tracking refs cannot skip unpublished commits. Fixing only the latest file does not clear a history finding.