regy

Regy is a browser control surface for the Pi coding agent. The integrated PC Agent CLI configures its Node/Pi dependencies, starts an Iroh endpoint, and retains the generic PTY bridge for remote shell features. The browser frontend is hosted separately on a CDN.

See the PC Agent CLI guide for first-run setup, Iroh start, pairing and revocation, Docker, supported hosts, and migration.

For the end-to-end CDN frontend workflow, see the CLI with frontend guide.

Install

The public installer installs the PC Agent and completes its managed Node/Pi setup. It does not start a server in the background:

curl -LsSf https://docs.regy.one/install.sh | sh

For a manual Cargo installation, run setup explicitly:

cargo install regy --locked
regy-pc-agent setup

Confirm the installed version with regy-pc-agent --version.

Requirements

• Rust and Cargo 1.91 to build the native agent.

• Node.js and pnpm only when developing the Vue frontend.

• On supported glibc Linux or macOS x86_64/aarch64, installing Node and Pi beforehand is optional: the CLI can install the pinned tools into the user's XDG data directory after consent.

• On other Unix targets, provide compatible tools explicitly. For example:

  npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  pi --version
  

--ignore-scripts follows Pi's documented safe npm installation path; Pi does not require npm lifecycle scripts for a normal install. The PC Agent launches pi --mode rpc, which exchanges strict JSONL records over stdin/stdout: one JSON command per LF-terminated input line, correlated responses and streamed events on output.

Security, credentials, and project trust

Pi has no built-in sandbox. It and its extensions run with the filesystem, process, network, and credential permissions of the user that starts the PC Agent. Run Regy as a dedicated least-privilege user, restrict PC_AGENT_ALLOWED_WORKDIRS, and use an OS/container/VM boundary for untrusted repositories or unattended work. Retained terminal commands are governed separately by PC_AGENT_ALLOWED_COMMANDS.

Pi RPC mode cannot show an interactive project-trust prompt. Project .pi resources and project .agents/skills are ignored under the default defaultProjectTrust: "ask" unless a trust decision was saved previously. For a trusted automation workspace, either save trust interactively first, set the global Pi policy deliberately, or configure PC_AGENT_PI_COMMAND="pi --approve". Do not approve repositories you have not reviewed; project trust controls resource loading, not tool sandboxing.

The Pi subprocess inherits provider environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY from the PC Agent. It also reads the launching user's ~/.pi/agent/auth.json, including credentials saved through Pi's /login. Keep the PC Agent and Pi under the same intended user and do not expose the auth file to the browser or control backend. In containers, pass only the required provider variables or mount a dedicated Pi home volume.

Official references:

• Pi quickstart
• RPC mode
• Providers
• Security and project trust
• Sessions
• Skills

PC Agent

The backend follows a DDD-style layout:

• src/backend/pc/domain: protocol, Pi RPC types, policy, and errors.
• src/backend/pc/operational: chat/session and skills use cases.
• src/backend/pc/presentation: outbound control-backend WebSocket and transport-neutral UI application routing.
• src/backend/pc/infrastructure: Pi subprocess, PTY, history, skills, reconnect, and host adapters.
• tests/backend/pc/unit: protocol, configuration, policy, and normalization tests.
• tests/backend/pc/integration: runtime, connection, Pi RPC, session, and PTY tests.

Run tests:

cargo test

Configure and run the integrated PC Agent:

cargo run --bin regy-pc-agent
cargo run --bin regy-pc-agent -- status
cargo run --bin regy-pc-agent -- start
cargo run --bin regy-pc-agent -- start -d
cargo run --bin regy-pc-agent -- stop
cargo run --bin regy-pc-agent -- --json --non-interactive --yes start

The first command opens the four-stage System/Pi/Pairing/Connectivity setup wizard in a TTY. Providers are not a Regy setup stage; Pi resolves provider authentication at runtime from its usual environment variables and ~/.pi/agent/auth.json. Later launches recheck readiness and show status. The native Iroh endpoint is the only browser transport; the static browser Worker reaches it through the configured relay route. Startup visibly reports the stable PC EndpointId; no browser TCP/WebSocket listener is created. Integrated configuration is schema 3 and defaults the frontend origin to https://regy.one. PC_AGENT_FRONTEND_ORIGIN may override that default with the exact HTTPS origin of a deployed frontend.

start stays attached to the terminal. start -d starts a terminal-independent server and prints only its frontend link; --json start -d prints one frontend_deep_link object. Detached output is logged to ${XDG_CACHE_HOME:-$HOME/.cache}/regy/pc-agent.log. stop gracefully stops either form, and succeeds harmlessly when no server is running.

The agent reads environment variables documented in ops/env/.env.example. Important Pi values are:

Pi stores sessions as JSONL below ~/.pi/agent/sessions/, grouped by working directory. A custom session location may be configured with Pi's --session-dir, PI_CODING_AGENT_SESSION_DIR, or sessionDir setting. Regy's PC_AGENT_PI_SESSION_DIR must point at the same location so history listing, resume, and deletion operate on the files created by Pi.

Skills

Regy-managed global skills are installed below ~/.pi/agent/skills/ by default. Workspace skills are installed below <workspace>/.agents/skills/ after canonical-path and allowlist checks. Pi also discovers user ~/.agents/skills/, trusted project .pi/skills/, package skills, paths in its settings.json, and repeatable --skill <path> arguments. When PC_AGENT_PI_GLOBAL_SKILLS_DIR is nonstandard, the PC Agent adds that directory as one --skill argument to every relevant Pi process.

PC_AGENT_SKILLS_PROVIDER defaults to skillspool, and PC_AGENT_SKILLS_API_BASE_URL defaults to https://skillspool.org. SkillsPool needs no token. The optional skills_sh provider requires a server-side Vercel OIDC bearer token in PC_AGENT_SKILLS_API_TOKEN; that token is never sent to the frontend or debug output.

Skill changes become authoritative in a fresh or restarted Pi process because discovery occurs at startup. Review downloaded SKILL.md files and scripts before use: path validation and archive confinement do not make community instructions trustworthy.

Structured chat protocol

All structured requests use a client-generated requestId; session operations additionally use sessionId. Streamed chat events carry eventSequence so reconnect snapshots can establish a cursor and replay only later events.

Browser/control-backend commands include:

• chat.session.create, chat.session.resume, chat.session.snapshot, and chat.session.close.
• chat.prompt, chat.abort, and chat.extension.respond.
• chat.history.list and chat.history.delete.
• models.list and directory.list.
• skills.search, skills.installed.list, skills.install, and skills.uninstall.

The PC Agent returns correlated acknowledgements, snapshots, history/model/directory/skill results, plus sequenced events for message start/delta/end, tool execution, usage, queue changes, compaction, retries, thinking level, session metadata, errors, exit, and resynchronization.

Pi extension UI methods select, confirm, input, and editor block on a correlated chat.extension.respond. Fire-and-forget notify, setStatus, setWidget, setTitle, and set_editor_text update browser surfaces without a response. Unknown methods remain visible and are cancelled rather than leaving Pi blocked.

History is source-bound: a conversationId must be resumed or deleted through the same PC Agent connection that returned it. IDs from two hosts must not be treated as interchangeable.

Retained terminal bridge

Structured Pi chat does not remove remote terminal support. The /agent protocol still supports session.create, terminal.input, terminal.resize, and session.kill, with session.started, terminal.output, session.exited, and correlated error responses. Terminal commands run in a real PTY under the configured command/workspace policy.

Containers

Build the self-contained image (Pi and provider tools/extensions are pinned):

docker build -f compose/backend/pc/Dockerfile -t regy-pc-agent .

The Dockerfile and native bootstrap pin the reviewed Node, Pi, Claude Code, Claude-auth extension, and Antigravity extension versions. It contains the native in-process iroh implementation, not a public-tunnel sidecar. Upgrade source metadata and Docker build arguments only after reviewing upstream code, licensing, and release notes.

Run it with one dedicated complete home volume so baked extensions survive Docker volume copy-up and setup/provider state persists:

docker run --rm \
  -it \
  -v regy-pc-home:/home/node \
  regy-pc-agent

Start the Iroh runtime explicitly:

docker run --rm \
  -v regy-pc-home:/home/node \
  -e PC_AGENT_FRONTEND_ORIGIN=https://app.example.com \
  regy-pc-agent --json --non-interactive --yes start

The image runs as the unprivileged node user. Bind-mounted workspaces must be readable/writable by that user (UID 1000 in the standard Node image), or the container must be started with an explicit user and compatible HOME. A read/write bind mount allows Pi to modify the host files.

API specification

The outbound /agent WebSocket and Iroh UI framing are documented at docs.regy.one.

Frontend

The Vue frontend lives in src/frontend.

pnpm frontend:dev
pnpm frontend:build

The application provides prompt-first chat creation, streaming Pi transcripts, model and thinking selection, source-bound history, a skills marketplace, workspace browsing, settings, and the retained terminal infrastructure for future remote-shell features.

Configuration migration

PC_AGENT_BACKEND_URL and PC_AGENT_TOKEN now select only the compatibility outbound runtime when both are present and no integrated subcommand is selected. For the integrated migration:

1. Install Pi and move provider authentication to environment variables or ~/.pi/agent/auth.json.
2. Replace deprecated CLI command/history/skill variables with PC_AGENT_PI_COMMAND, PC_AGENT_PI_SESSION_DIR, and PC_AGENT_PI_GLOBAL_SKILLS_DIR.
3. Align Pi's session directory with Regy's history directory.
4. Move global managed skills to ~/.pi/agent/skills/; workspace skills remain in .agents/skills/.
5. Review project trust for every automated workspace and restart the PC Agent so Pi reloads settings and skills.
6. Keep PC_AGENT_DEFAULT_COMMAND only if generic terminal sessions are required.

The browser preferences migration discards obsolete access-mode/model fields and retains safe UI preferences. Existing Pi JSONL sessions are discovered directly; session identifiers remain scoped to their source PC Agent.