Remote Agent

AI Remote Development Gateway for MCP, CLI, SSH, and persistent daemon jobs

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.

License: MIT Version

中文文档

---

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.

---

Architecture Overview

agentport is split into a local agent gateway and a remote Linux daemon:

AI desktop tool
  -> CLI daemon gateway, native MCP tools, or SSH recovery
  -> local agentport gateway
  -> remote daemon HTTP API
  -> remote Linux workspace

The local side registers MCP tools when available, provides a CLI fallback for tools that can run terminal commands, reads private connection config, and turns daemon errors into agent-readable messages. The remote daemon performs token auth, safe path checks, file operations, command execution, persistent development jobs, audit logging, health checks, Dashboard responses, and hot config 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

Feature	Description
Remote File R/W	remote_read / remote_write / remote_stat
Remote Search	remote_glob search file paths, remote_grep search file contents
Command Execution	remote_bash for simple commands, remote_script for multi-line scripts
Batch Operations	remote_batch up to 20 operations per request
Native MCP Tools	Structured remote_* tools when the host supports custom MCP servers
CLI Daemon Gateway	node cli.js status and node cli.js job ... for stable development workflows
Persistent Jobs	Remote daemon jobs for tests, builds, logs, status, and cancel
Async Execution	remote_exec_async + remote_task compatibility for long-running tasks
Config Hot Reload	remote_config modify remote config without restart
Execution Backpressure	Queue timeout returns clear 429 with exec running/max/queued state
Dynamic Connections	Switch between multiple servers without restarting MCP
Multi-session Reuse	One local core instance per software key, extra sessions attach via local proxy broker
Health Check	Automatic remote service status detection
Encoding Handling	Auto base64 encode special chars, clean CRLF/BOM

---

Agent Integration Priority

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

1. SSH-first CLI for stable base operations: use --route ssh for health, read/write, stat, glob, grep, and one-off command execution.
2. CLI daemon gateway for long-running development: use node cli.js status and persistent job commands for tests, builds, polling, and durable logs.
3. Native MCP for convenience when available: if remote_* tools are visible and stable, use them for quick structured operations.
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 /path/to/workspace/AGENTS.md
node cli.js bash "pwd && ls -la" --cwd /path/to/workspace
node cli.js bash "pwd && ls -la" --route ssh --json
node cli.js write /path/to/workspace/tmp.txt --content "hello"

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 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:

Setting	Default	Description
EXEC_TIMEOUT_MS	120000	Timeout for a running command
EXEC_MAX_CONCURRENCY	4	Maximum commands running at the same time
EXEC_QUEUE_TIMEOUT_MS	15000	Maximum time a request waits for an execution slot

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.168.31.183",
      "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.168.31.183: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 remote daemon

Only use this section for first-time server bootstrap or planned daemon maintenance. Normal client installs should not overwrite remote daemon files.

ssh USER@SERVER "mkdir -p /path/to/daemon"
scp server/server.js server/agentport-manager.sh server/package.json USER@SERVER:/path/to/daemon/
scp local/server/.env USER@SERVER:/path/to/daemon/
ssh USER@SERVER
cd /path/to/daemon
npm install
nohup bash agentport-manager.sh >> boot.log 2>&1 &

---

Supported AI Tools

AI Tool	MCP Config Path (Windows)	MCP Config Path (macOS/Linux)
WorkBuddy	C:\Users\<user>\.workbuddy\mcp.json	~/.workbuddy/mcp.json
Claude Desktop	C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json	~/.config/Claude/claude_desktop_config.json
Cursor	<project>\.cursor\mcp.json	<project>/.cursor/mcp.json
Windsurf	C:\Users\<user>\.codeium\windsurf\mcp_config.json	~/.codeium/windsurf/mcp_config.json
Tools without custom MCP	Use node cli.js ... through Bash/terminal	Use node cli.js ... through Bash/terminal

---

Tool List

Tool	Function
remote_ssh_info	Scan local SSH environment (keys, config, known hosts)
remote_health	Check remote service reachability
remote_read	Read remote file (ETag cache)
remote_write	Write remote file (auto clean CRLF/BOM)
remote_stat	Get file metadata
remote_glob	Search by glob pattern
remote_grep	Search remote file contents
remote_bash	Execute remote command
remote_script	Execute multi-line script
remote_batch	Batch operations
remote_exec_async	Async execution
remote_task	Query async task
remote_config	Config hot reload
remote_status	Connection diagnostics

For detailed usage, see SKILL.md

---

Directory Structure

agentport/
|-- SKILL.md                         # Complete agent documentation
|-- README.md                        # This file (English)
|-- README_CN.md                     # Chinese documentation
|-- AGENT_GUIDE.md                   # Agent install and usage guide
|-- index.js                         # MCP server main program
|-- cli.js                           # CLI fallback for tools without native MCP
|-- package.json                     # Client dependencies
|-- agentport.example.json    # Public config template
|-- sync.cjs                         # Variable sync script
|-- test.cjs                         # Test script
|-- LICENSE                          # MIT License
|-- CHANGELOG.md                     # Version changelog
|-- local/                           # Local private config directory
|   |-- config-guide.md              # Configuration guide
|   |-- connections.json.example     # Multi-server config example
|   `-- server/
|       `-- .env                     # Server config generated by sync.cjs
`-- server/
    |-- server.js                    # Remote daemon process
    |-- agentport-manager.sh  # Process guardian script
    |-- setup-autostart-agentport.sh           # Autostart config script
    |-- dashboard.html               # Web Dashboard UI
    |-- .env.example                 # Server config template
    `-- package.json                 # Server dependencies

Configuration Files

File	Location	Description
agentport.json	local/	Main configuration (copy from agentport.example.json)
connections.json	local/	Multi-server connections (optional, see connections.json.example)
.env	server/	Server configuration (auto-generated by sync.cjs)

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

Feature	Description
Service Status	View Node.js, dependencies, port, disk status
Audit Statistics	View request stats, success rate, by type/client analysis
Error Logs	View recent error logs
Config Management	View and modify server config (requires Admin Token)

---

Autostart Configuration

Method 1: Using setup-autostart-agentport.sh (Recommended)

# SSH to remote server
ssh USER@SERVER
cd /path/to/daemon

# Install autostart
bash setup-autostart-agentport.sh install

# Check status
bash setup-autostart-agentport.sh status

# Uninstall autostart
bash setup-autostart-agentport.sh uninstall

Method 2: Manual crontab configuration

# Edit crontab
crontab -e

# Add the following line
@reboot /path/to/daemon/agentport-manager.sh # agentport autostart

Method 3: Using systemd (Optional)

Create /etc/systemd/system/agentport.service:

[Unit]
Description=agentport daemon
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/daemon
ExecStart=/bin/bash /path/to/daemon/agentport-manager.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable:

sudo systemctl enable agentport
sudo systemctl start agentport

---

Security Features

• Workspace Isolation: File operations restricted within WORKSPACE_ROOT
• Token Authentication: Client token + admin token
• Path Restrictions: Prevent unauthorized access
• Script Interpreter Whitelist: Only allow safe interpreters
• Command Execution Limits: Configurable ALLOW_BASH_EXEC and ALLOWED_COMMANDS

---

Version History

See CHANGELOG.md

---

License

MIT License - See LICENSE

---

Contributing

Issues and Pull Requests are welcome!