AgentProcs

Keep development services alive, observable, and controllable across separate AI coding-agent tool calls.

Coding agents often start an API, web app, or worker in one shell, then lose track of the process on a later tool call. AgentProcs keeps those services under a per-session daemon so the next call can inspect logs, check status, restart a process, or stop everything cleanly.

AgentProcs is for developers using agentic coding workflows on Linux and macOS (Unix only). It provides same-user process supervision, not sandboxing; managed commands retain your filesystem and network access. See Architecture and security boundary for details.

• A daemon persists across CLI calls, with project and session isolation.
• Readiness checks and dependency ordering start services in the right sequence.
• Durable indexed logs and JSON status keep process state available to agents and scripts.
• Restart policies and file watching recover development services; an optional proxy gives them named localhost URLs.

This is a real, reproducible local run. Follow the demo instructions to play or record it yourself.

Engineering proof: Unit tests live alongside the source, with property, integration, and end-to-end tests; current v0.6.2 release binaries target Linux and macOS on x86_64 and ARM64.

Quick start · Architecture and security

Install

cargo install agent-procs

Quick start

# Start a process
agent-procs run "npm run dev" --name server

# Auto-restart on crash (up to 5 times)
agent-procs run "npm start" --name api --autorestart on-failure --max-restarts 5

# Restart when source files change
agent-procs run "npm run dev" --name server --watch "src/**"

# Wait for it to be ready
agent-procs wait server --until "Listening on" --timeout 30

# Check output
agent-procs logs server --tail 50

# See what's running
agent-procs status

# Stop it
agent-procs stop server

Config file

Create an agent-procs.yaml to manage multiple processes together:

session: myproject                          # optional — isolates this project's processes
proxy: true                                 # optional — enables reverse proxy
proxy_port: 9095                            # optional — pin proxy to a specific port

processes:
  db:
    cmd: docker compose up postgres
    ready: "ready to accept connections"
    autorestart: always
    max_restarts: 3
  api:
    cmd: ./start-api-server
    cwd: ./backend
    env:
      DATABASE_URL: postgres://localhost:5432/mydb
    ready: "Listening on :8080"
    port: 8080
    depends_on: [db]
    autorestart: on-failure
    watch:
      - "src/**"
      - "config/*"
    watch_ignore:
      - "*.generated.ts"

Processes start in dependency order; independent ones run concurrently.

agent-procs up                    # start all
agent-procs up --only db,api      # start specific ones
agent-procs down                  # stop all

Field reference

Per-process fields:

Top-level fields:

Reverse proxy

Give processes stable named URLs instead of port numbers. Opt-in via proxy: true in config or --proxy on the CLI.

$ agent-procs up
Proxy listening on http://localhost:9090
started api (http://api.localhost:9090)
started web (http://web.localhost:9090)

• Processes without an explicit port get one auto-assigned (4000-4999 range)
• PORT and HOST=127.0.0.1 are injected into the process env (user env takes precedence)
• Each session gets its own proxy port, so two projects can both have api without conflict

Ad-hoc usage without a config file:

agent-procs run "node server.js" --name api --port 3001 --proxy
# → http://api.localhost:9090

Commands

Restart policies

Automatically recover from crashes without agent intervention.

# Restart on non-zero exit, up to 5 times with 2s delay
agent-procs run "npm start" --name api \
  --autorestart on-failure --max-restarts 5 --restart-delay 2000

# Always restart (even clean exits), unlimited attempts
agent-procs run "worker" --name bg --autorestart always

When max_restarts is exhausted, the process enters Failed state. Manual stop disables auto-restart; restart re-enables it and resets the count.

Supervisor annotations ([agent-procs] Restarted, Max restarts exhausted) are written to disk logs and visible in logs --tail, --follow, and the TUI.

File watch mode

Auto-restart processes when source files change.

agent-procs run "npm run dev" --name server --watch "src/**" --watch "config/*"

• Uses OS-native file watching (FSEvents on macOS, inotify on Linux) with 500ms debounce
• .git, node_modules, target, and __pycache__ are always ignored
• Add --watch-ignore "*.log" for additional ignore patterns
• Watch restarts reset the restart count (they're intentional, not crashes)
• File changes can revive a Failed process

Sessions

Use --session to isolate process groups (e.g. per-project):

agent-procs --session projectA run "make serve" --name app
agent-procs --session projectB run "make serve" --name app
agent-procs --session projectA status   # only shows projectA's processes

Alternatives

AgentProcs is intentionally narrow for host-process control in agent-driven development; other tools fit different operating models. Linked tool names and notes point to official documentation.

Use another tool when

• nohup fits when one command only needs to survive logout and PID/files are enough.
• Choose tmux when a reconnectable interactive terminal is the main need.
• PM2 suits apps that need an established manager with Node support, restarts, boot integration, metrics, or clustering.
• Docker Compose is the better model when the stack should use containers, images, networks, volumes, and healthchecks.
• Overmind fits a project that already has a Procfile and needs direct tmux attachment.
• Foreman works for a lightweight Procfile workflow or export to a native supervisor.

Architecture and security boundary

Each Quick start command is a short-lived CLI client, while a per-session daemon persists across invocations and owns the control plane. CLI requests cross a Unix domain socket whose 0700 parent directory limits access to the current user; the daemon supervises process groups, durable session logs, and the optional Reverse proxy.

AgentProcs provides process supervision, not sandboxing: managed commands retain the current user's filesystem and network access. Use a container or VM when isolation is required; see Sessions for operational separation and SECURITY.md for the complete security model.

Exit codes