# Headless session server

**The canonical client-neutral server for a Po session.**

`po-server` embeds a `DirectHarnessRuntime` and its typed session services in one process. It does not launch a second Pi process or expose an internal filesystem transport. Clients use the authenticated HTTP surface and the `/api/ws` WebSocket endpoint. A command-line server owns one session; the exported hub and session manager can host more than one session in a process.

The `@agimon-ai/po` core package owns this executable and the `@agimon-ai/po/server` API. It is a standalone process, not a Pi extension. Do not add it to `.po/modes.yaml`.

## Install

Requires Node.js 24 or newer and the packages your Po configuration names.

```bash
npm install -g @agimon-ai/po
```

Run `po sync` in the session repository to install the configured packages and the global web build. The server composes each scope live from configuration, so later configuration changes need no restart.

## Quick start

Create an owner-only token file, then pass harness arguments after `--`:

```bash
token_file="$(mktemp)"
(umask 077; openssl rand -base64 32 > "$token_file")

po-server \
  --auth-token-file "$token_file" \
  -- --major-mode copilot
```

New server workers launched by Po Web, Desktop, or `po-server` default to 10 GB of V8 old-space. Override this with `NODE_OPTIONS=--max-old-space-size=<MiB>`; an operator heap setting wins. This sets old-space only, not an RSS cap or reservation. Custom launches that set `PO_SERVER_SUPERVISED=1` pick their own Node flags.

The server listens on loopback port 7533 by default. Use `--web 9000` to select another port. The option name is retained for CLI compatibility, but the listener is the server's normal client-neutral HTTP and WebSocket surface, not an optional browser-only service.

The token is read from the file, not the command line. Keep the file private. A direct client presents the token to the HTTP routes and `/api/ws`; Po Web can proxy the endpoint after applying its own browser and remote-access controls.

## How it works

Startup composes the global scope from configuration and imports the eligible server plugins from their packages' built entries. It then creates the direct harness, session service, and package API handlers in process. The listener provides:

- `/api/ws`, an authenticated WebSocket carrying Chord 1.2 link frames;
- `/api/health`, an unauthenticated readiness check;
- `/api/workspaces/<workspace-id>/sessions` and related routes for discovery and channel access; and
- session package APIs below `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/...`.

The Pi protocol exposes typed management, hub, and session services. Session calls operate directly on the same runtime that owns the session journal. No raw command bridge, child-process fallback, or separate package API transport sits between a client and the runtime.

## Security

The server binds to loopback by default and requires the token for every route except `/api/health`. A token file keeps the capability out of process listings. The server is not a sandbox: the harness, extensions, and server plugins run with the account's authority.

Po Web owns browser authentication, remote tunnels, device cookies, and passkeys. When it proxies a session, browser code does not need the server token. Do not publish the server listener without an authenticated boundary.

Read [Security and trust boundaries](security.md) before sharing a listener or token.

## Guides

| Guide                                 | What it covers                                                    |
| ------------------------------------- | ----------------------------------------------------------------- |
| [Getting started](getting-started.md) | Installation, options, live composition, and web integration      |
| [Lifecycle](lifecycle.md)             | In-process startup, readiness, shutdown, and history ownership    |
| [IPC](ipc.md)                         | The `/api/ws` protocol, typed operations, HTTP routes, and replay |
| [Session APIs](api.md)                | `poServer` plugins, package handlers, and TypeScript exports      |
| [Security](security.md)               | Tokens, listener exposure, trusted code, and data boundaries      |

## License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See [LICENSE](../../LICENSE) and https://agimon.ai/licensing.