Portrail

An HTTP API in front of the coding agent on your own machine.

Install Portrail next to Codex or Claude Code, give it a folder and an API key, and drive the agent from anything that can make an HTTP request — curl, a script, Zapier, Make, n8n, your own app. The agent does real work: it runs commands and edits files. Your rules decide what it may do without asking.

$ npm install -g portrail
Five-minute quickstart

MIT licensed · Node.js 24+ · macOS & Linux

curl -X POST http://127.0.0.1:7431/v1/runs \
  -H "Authorization: Bearer prt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "codex",
    "workspace": "my-app",
    "prompt": "Fix the failing test in auth.ts",
    "wait": 300
  }'

That request returns when the agent is done, with what it did and what it said.

Who this is for

Developers using Codex or Claude Code

Keep the agent and the login you already have on your machine, and reach it from a script, a cron job or another terminal.

Automation builders

Make, n8n and Zapier scenarios call one HTTP endpoint and get back what the agent did. Idempotency keys make retries safe.

Teams evaluating agent tooling

Every operation the agent proposes is checked at one decision point, and every decision is recorded with the rule that produced it.

What you get

Both agents

Codex and Claude Code, through their own permission hooks, using the login you already have — no OpenAI or Anthropic keys copied into your automation tool. Portrail itself is reached with its own bearer key.

One decision point

Every operation the agent proposes is checked against your rules before it starts. A refused operation is never started, and the agent is told why. What an allowed operation then does is the agent's — and its sandbox's — business, not Portrail's.

A real API

Runs, sessions, resumable event streams, cancel, steer, wait for synchronous callers, and idempotency keys for automations that retry.

Reachable from anywhere

Bind to an interface with TLS, put it behind a proxy, or portrail start --tunnel for a public URL on a laptop behind NAT.

Honest about failure

If Portrail loses track of an agent mid-run, the run ends as outcome_unknown — never a silent success, never a replay. A run that finished but had something refused says so.

Runs as a service

portrail service install on macOS or Linux. portrail doctor checks Node, finds your agents, and tells you what to fix.

How it works

Both agents ask permission before acting. Codex sends a request over its app-server protocol; Claude Code calls a hook. Portrail answers those questions from your rules, which means it governs what the agent does without being a sandbox around it.

Each operation the agent proposes is checked before it starts. A refused operation is never started, and the agent is told why.

curl · SDK · Make · n8n
Portrail HTTP API
Codex · Claude Code

“May I run npm test?” — the agent asks before it acts.

Allow or deny, from your rules, at one decision point.

Rules

Portrail ships with an allow/deny list: reads and workspace writes are free, a named set of development commands is free, secret files are refused for reading and writing, obviously destructive and network commands are refused, and anything unmatched is refused — or, if you put it in decide.ask, portrail run asks you at the terminal. Compound commands are judged one segment at a time.

It is a starting point for a repository you trust, not a security boundary against hostile input — read the security model before pointing an agent at untrusted content.

$ portrail run --workspace my-app \
    "Add a --version flag to the CLI"

  ● reading  src/cli.ts            allowed
  ● writing  src/cli.ts            allowed
  ● exec     npm test              allowed
  ● exec     curl https://…        denied

  succeeded · 1 operation refused

Requirements

  • Node.js 24 or newer. Portrail uses the SQLite that ships with Node, so npm install never compiles anything.
  • Codex CLI signed in, and/or Claude Code signed in.
  • macOS or Linux. portrail doctor checks all of it and tells you what to fix.

Status

Early release. Tested on macOS and Ubuntu 24.04 with both agents: real runs, tarball install, the systemd service, crash recovery under kill -9, and a Cloudflare tunnel from the public internet.

The API is stable within 0.x for the routes documented in the API reference. Published versions are listed on Releases and in the changelog.

Documentation