Agent Proxy

agent-proxy is a Python CLI for persistent agent workspaces and Codex session coordination.

The primary commands are:

• agent-proxy enable
• agent-proxy restart
• agent-proxy init <role>
• agent-proxy hire <role> <name>
• agent-proxy list
• agent-proxy status
• agent-proxy connect <agent> [working_dir]
• agent-proxy stop <role>

There is also an internal agent-proxy daemon command used by the systemd service.

Features

• agent-proxy init <role> creates a role workspace with memory and daily notes
• agent-proxy init <role> asks the daemon to spawn Codex and returns the managed PID
• agent-proxy hire <role> <name> creates or reuses a named agent and returns its managed PID
• agent-proxy enable installs and starts the systemd daemon service
• agent-proxy restart restarts the systemd daemon service
• agent-proxy restart also allows desired roles to come back under the restarted master
• if a managed autostart role dies, the daemon will try to restart it after about 10 seconds
• agent-proxy list shows initialized agents
• agent-proxy status shows the daemon/agent process tree
• agent-proxy connect <agent> [working_dir] opens a command-line chatbot for the managed role session
• agent-proxy stop <role> queues a stop request for the monitor daemon
• the master also serves an OpenAI Responses-style POST /v1/responses API and a browser chat UI at GET /
• the master also serves POST /hire for creating named agents
• when the daemon starts, it also starts the default manager agent

Installation

cd agent-proxy
make install

Installation does not automatically enable the daemon. Use agent-proxy enable explicitly.

Or directly:

pip install -e .

Usage

Initialize a role workspace:

agent-proxy init researcher

This creates:

~/.agent_proxy/researcher/
├── SOUL.md
├── AGENTS.md
├── memory/memory.md
└── notes/daily-YYYY-MM-DD.md

The generated instructions tell the agent to write important long-term information into memory/memory.md and write task summaries into the daily note.

After the workspace is created, agent-proxy init <role> asks the daemon to spawn the role process and prints the managed PID.

Hire a named agent from the CLI:

agent-proxy hire engineer alice

This prints:

engineer_alice 12345

Install and start the systemd service:

agent-proxy enable
agent-proxy enable --ip 0.0.0.0 --port 7011
agent-proxy restart

The command uses sudo internally for the privileged install and systemctl operations. When the daemon comes up, it also creates or reuses ~/.agent_proxy/manager/ and keeps the manager agent running.

List available agents:

agent-proxy list
agent-proxy status

When the master is running, it also serves:

http://0.0.0.0:7011

HTTP responses API:

curl -N http://127.0.0.1:7011/v1/responses \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"model":"engineer_alice","input":"hello","stream":true}'

/v1/responses follows the OpenAI Responses API shape for request and response payloads. If AGENT_PROXY_API_KEY is configured for the service, API requests must send Authorization: Bearer <key>.

Open http://127.0.0.1:7011/ in a browser for the streaming chat UI.

Hire a named agent:

curl -s http://127.0.0.1:7011/hire \
  -H 'Content-Type: application/json' \
  -d '{"role":"engineer","name":"alice"}'

This creates a workspace like:

~/.agent_proxy/engineer_alice/

Queue a connection request for an agent, defaulting to the current directory:

agent-proxy connect researcher
agent-proxy connect researcher /home/li/project/collection-pip

If the agent becomes ready, connect returns its managed PID. If the daemon cannot make it ready, connect exits with not ready. If the agent becomes ready, connect opens a command-line chatbot loop. If the daemon cannot make it ready, connect exits with not ready.

The optional working_dir argument is task context for the agent. Codex itself still runs from the agent workspace. On connect, the CLI first sends:

Now let us work on working dir: <working_dir>

Queue a stop request for an agent:

agent-proxy stop researcher

Notes

• connect targets a daemon-managed pseudo-terminal session. The daemon records the message Now let us working on <working_dir> and launches Codex from that directory inside the managed session.
• after a daemon restart, roles marked for autostart are spawned again by the master
• the daemon also ensures the default manager agent is running after startup or restart
• if an autostart role crashes, the master retries it after about 10 seconds instead of leaving it down permanently
• stop queues a stop request. The daemon terminates the tracked Codex process for that role if it still exists.
• init is daemon-managed. It returns a PID instead of entering an interactive shell.