---
name: multi-agent-serve
description: "Start the local contract server a client (the macOS toolbox, a web page) reads runs, commands, questions, issues and worktrees from, on 127.0.0.1 behind a per-start token. It stops by itself after 15 idle minutes. Use when a client asks for the HTTP carrier instead of the CLI."
user-invocable: true
argument-hint: "[--port <n>] [--idle-minutes <n>] [--allow-origin <origin>] [--print-token]  -  all optional, --allow-origin may repeat; binds 127.0.0.1 only"
metadata:
  language: en
  not-for: status, autopilot-on
---

# multi-agent serve  -  the contract over HTTP, on demand

**Input**: $ARGUMENTS

Starts `contract-server.mjs`: the same JSON the CLI prints (`runs-index.mjs`,
`commands.mjs`, `issues.mjs`, `worktrees.mjs`, `launch-request.mjs`,
`answer-question.mjs`), served over HTTP on `127.0.0.1` for a client that would
rather hold a socket than spawn a process per read. Routes, schemas and the
versioning rule are in the package's `pipeline/contract/README.md` and
`manifest.json`.

It is never a service. It runs until 15 minutes pass without a request
(`--idle-minutes`) or it gets SIGTERM, and removes its token file either way.

## Start it

Run it in the background (it keeps running), then read its first stdout line:

```bash
node "$HOME/.claude/scripts/contract-server.mjs" $ARGUMENTS
```

The ready line is one JSON object: `url`, `port`, `pid`, `tokenFile`,
`idleMinutes`. Report `url`, `pid` and `tokenFile` in `outputLanguage`.

- **Never print the token**, and do not pass `--print-token` yourself: it puts
  the token on stdout, which lands in this transcript. It exists for a client
  that spawns the server as its own child. The token is in `tokenFile` (0600).
- `--host` accepts only `127.0.0.1`; anything else (0.0.0.0, ::, a LAN address)
  exits 2. Say so rather than retrying another address.
- `--allow-origin` is for a browser page the user named; without it no Origin
  is accepted. A request that carries an Origin is always served redacted.

## Stop it

Send SIGTERM to the `pid` from the ready line, and only that pid:

```bash
kill -TERM <pid>
```

Or leave it: it exits on its own when idle.

## What it will not do

There is no route that merges, marks ready, runs a command or starts a host.
`POST /v1/launch` and `POST /v1/runs/{id}/resume` return the argv and
environment `launch.json` declares; the client starts the process.
`POST /v1/runs/{id}/answer` accepts only an option the run's pending question
offered. `POST /v1/runs/{id}/kill` and `POST /v1/gc` act only on a second
request carrying the single-use confirm token the first one returned, and a
kill never deletes the remote branch or the logs. Autopilot can be turned off
over HTTP, never on.
