self-hostable Apache-2.0 core

The SSH of the
agent world.

agent-exec turns a machine into a self-describing endpoint for AI agents. Give agents a machine endpoint; the machine explains itself, and the server enforces what agents may do.

Developer preview boundary: not a sandbox, not SSH-compatible, and not an SSH replacement. Fresh installs only allowaexec --version. Useful operations come from starterkits or plugins you choose. Use localhost, VPN, firewall, or TLS-terminated trusted networks.
Quick install GitHub NPM X
agent handoff
Quick start

Install, start, share. Then paste.

aexecis the official command.aeis the short alias for daily use. The default setup is a safe self-test. Add a starterkit or plugin when you want useful operations.

bash
# 0. Check requirements: Node.js 20+ and npm
$ node --version
$ npm --version

# 1. Install
$ npm install -g @to-agent/agent-exec@latest

# 2. Set up local config and API_KEY
$ aexec setup

# 3. Start serving
$ aexec start

# 4. Generate a prompt for an AI agent
$ aexec share

# Optional useful handoff: expose installed AI tools as plugins
$ aexec starterkit
$ aexec restart
$ aexec share
Requirement: Node.js 20+ is required because agent-exec currently usesmarked@18for Markdown rendering. Ifnode --versionis below v20, install Node.js 20+ using the OS/package-manager-supported path for this machine, then retry.
Upgrade:npm i -g @to-agent/agent-exec@latestaexec update is only a convenience wrapper for that npm path. It verifies the active command and does not repair package-manager or PATH state.
AI install prompt
Install agent-exec on this machine.

Run:
1. Check that Node.js 20 or newer and npm are available.
   agent-exec currently uses marked@18 for Markdown rendering, and marked@18 requires Node.js 20 or newer.
   If node is below v20, install Node.js 20 or newer using the OS/package-manager-supported path for this machine, then retry.
   node --version
   npm --version
2. Install globally:
   npm install -g @to-agent/agent-exec@latest
3. Run:
   aexec setup
4. Start the server:
   aexec start
5. Run:
   aexec share
6. Show me the generated share prompt.

Do not edit project files unless needed.
Do not expose agent-exec to the public internet.
Do not use --public unless I explicitly ask for network access.
Do not add broad ACL rules such as allow "*".
Fresh installs should only allow:
  aexec --version

Useful operations are not exposed by default. If I ask for a useful plugin demo, run:
  aexec starterkit
  aexec restart
  aexec share
and show me the generated settings before proceeding.

If any command fails, stop and show me the error plus the next recommended command.
Standalone skill: agent-exec.install.skill.md
aexec share
You have access to this machine through agent-exec.

URL:
http://<agent-exec-host>:3333

API_KEY: <API_KEY>

Start here:
http://<agent-exec-host>:3333/SKILL.md
How it works

A machine that explains itself to agents.

agent-exec does not require a special SDK or model-specific integration. The machine publishes a small HTTP entry point and the agent follows the documents.

01

Read /SKILL.md

The public entry point tells the agent how to start.

02

Inspect /api/acl

The agent checks what commands are allowed before executing.

03

Discover /api/plugins

Optional plugin documentation is loaded only when the agent needs it.

04

POST /api/exec

The server executes only what the ACL permits.

Agent receives machine endpoint + API_KEY ↓ GET /SKILL.md GET /api/acl GET /api/plugins POST /api/exec ↓ allowed operation runs on the machine
Extensions

Extend with plugins and skills.

Plugins add tool-specific documentation and optional command behavior. Skills keep detailed usage out of the initial prompt and let agents load detail only when needed.

plugin commands
$ aexec plugin list
$ aexec plugin create --name=mytool --command=mytool
$ aexec plugin doctor
Execution boundary

Argument arrays, not shell execution.

/api/execuses JSON body arguments for execution. GET requests and query-string commands never execute.

JSON body only

Commands are sent as{"args":["command","arg"]}.?cmd=and?args=are not execution inputs.

No shell interpretation

agent-exec runs the submitted argument array. Operators such as&&,;, pipes, redirects, and subshell syntax are not interpreted by agent-exec itself.

Deny before allow

Allow and deny rules are enforced server-side. Plain string rules require an exact command-and-argument match, and deny rules win before allow rules. The README covers glob and regex details.

Trusted plugins are host code

Trusted plugins should be reviewed like code running as the agent-exec OS user. Do not install unreviewed trusted plugins.

Safety boundary

The agent discovers. The server decides.

agent-exec is default-deny. Fresh installs only allowaexec --version. Useful operations are added explicitly through starterkits, plugins, and reviewed ACL rules. Use ACLs, least-privileged OS users, and network controls. It is SSH-like access for AI agents, not SSH-compatible and not an SSH replacement.

Do not expose plain HTTP agent-exec to the public internet. Use localhost, VPN, firewall, TLS termination, or another trusted network boundary. Treat the API_KEY as machine execution capability and rotate it after canary tests.

Any HTTP-capable agent can start here.

If your agent can make HTTP requests, it can start with agent-exec.

Try agent-exec Back to to-agent.com