Overview

What is the runtime?

The Phrony runtime is the official open-source implementation of the Phrony Agent Spec. It stores published agent manifests, activates versions for execution, runs sessions (model loop, tools, policies, limits, and human-in-the-loop), emits structured traces, and returns results. Applications call the runtime over gRPC; the runtime is where agents live.

You'll work with two programs from the runtime repository. One is the always-on server (a daemon — a background process that keeps running and waits for requests); the other is the command-line tool you type into:

Concept examples

Manifest → runtime (your app does not embed the agent loop):

# You write agent.yaml locally
$ phrony agents publish ./my-agent/agent.yaml # runtime stores version 1.0.0
$ phrony agents deploy demo/my-agent@1.0.0 # version 1.0.0 is now "live"
$ curl -X POST .../agent.run # or: phrony run demo/my-agent

Session (one execution from start to finish):

phrony run demo/echo-agent
→ session id: run_abc123
→ status: running → awaiting_input → completed

gRPC (how the CLI talks to the daemon — you usually don't write this yourself):

$ export PHRONY_RUNTIME_ADDR=127.0.0.1:7777
$ phrony status # CLI → gRPC → phrony-runtime

The Node-based Phrony CLI used for manifest authoring and packaging is separate. This documentation covers the Go runtime daemon and its operator CLI.

Prerequisites

• Docker Desktop or Docker Engine (recommended local path)
• Go 1.25+ (to install the operator CLI)

Run with Docker (recommended)

The official runtime image is published to GitHub Container Registry as ghcr.io/phrony-platform/phrony-runtime:latest on each GitHub release.

Download the Compose file from /runtime/docker-compose.yml (or copy it from src/content/runtime/docker-compose.yml in the docs repository), then start Postgres and the runtime:

$ mkdir phrony-runtime && cd phrony-runtime
$ curl -fsSLO https://phrony.com/runtime/docker-compose.yml
$ docker compose up -d --wait

The stack listens on gRPC port 7777 (127.0.0.1:7777 from your machine). Stop it with docker compose down.

Install the operator CLI:

$ go install github.com/phrony-platform/runtime/cmd/cli@latest
$ mv -f "$(go env GOPATH)/bin/cli" "$(go env GOPATH)/bin/phrony"

Then verify connectivity:

$ phrony status

Run the runtime on your host (development)

When you are changing Go code, run only Postgres in Compose and start phrony-runtime locally:

$ docker compose up -d postgres --wait
$ make migrate
$ make serve

Do not run make serve on the host while the compose runtime service is also using port 7777.

Install binaries

Released builds

Install the runtime daemon with go install:

$ go install github.com/phrony-platform/runtime/cmd/phrony-runtime@latest

Install the operator CLI as phrony:

$ go install github.com/phrony-platform/runtime/cmd/cli@latest
$ mv -f "$(go env GOPATH)/bin/cli" "$(go env GOPATH)/bin/phrony"

go install names the binary after the package directory (cli); rename it to phrony to match the operator CLI.

Ensure $(go env GOPATH)/bin is on your PATH. You still need Postgres (and typically Docker Compose) unless you provide your own database URL.

Build from a local checkout

$ make build
$ export PATH="$(pwd)/bin:$PATH"

This produces bin/phrony-runtime and bin/phrony.

Install only the operator CLI

From the repository root:

Prefer make install-cli-path when you want flags like --namespace to reach the CLI without Make interpreting them.

Environment variables

Copy .env.example to .env for host-side tools. Load the file before running binaries directly:

$ set -a && source .env && set +a

make targets (serve, cli, migrate, …) load .env or .env.example automatically.

The Compose file sets RUNTIME_DATABASE_URL (hostname postgres), RUNTIME_GRPC_ADDR=0.0.0.0:7777, and a dev RUNTIME_SECRETS_ENCRYPTION_KEY on the runtime service.

Session provider API keys (for example ANTHROPIC_API_KEY) are resolved on the operator host when you run phrony run—from the shell environment, from -e / --env-file, or supplied by your backend in RunSession—not configured on the runtime daemon. See run and Secrets.

phrony-runtime commands

When running the daemon outside Docker, with Postgres up and .env loaded:

$ phrony-runtime serve

serve applies schema migrations (unless you pass --skip-migrate), then starts the gRPC server.

Migrations only:

$ phrony-runtime migrate

Local development

Run make with no arguments for the full target list.

Tool dispatch

The runtime authorizes every tool call, routes worker-backed tools over the Work gRPC stream, routes MCP-backed tools over Streamable HTTP, and records invocations in Postgres. See Tool dispatch for the execution loop, MCP tool dispatch, failure modes, workers, integrity allowlist, and recovery.