run

Synopsis

$ phrony run AGENT[@VERSION] [flags]

Description

Starts a new runtime session for an agent.

AGENT is namespace/name (for example demo/echo-agent). With no version suffix, the runtime uses the active deployed version from the latest deploy (or rollback).

You may pass an explicit version as AGENT@VERSION or with --version / -v. That version must match the currently active deployment. Published-but-not-deployed versions, retired versions, deprecated versions, and non-active historical versions are rejected.

By default, phrony run calls the runtime in detached mode: the daemon runs the session in the background, prints the new session id, and the CLI exits. Use sessions attach when the session reaches awaiting_input, or pass --attach / -a to start the session and attach in one command.

With --attach, the CLI calls RunSession (background driver) and then RunSessionInteractive with only the session id. Ctrl+C detaches from the stream; the session keeps running until it finishes or you sessions cancel. Ctrl+D still ends the interactive stream when you are at a prompt (same as before). Multiple terminals can attach to the same running session.

When the published Agent declares secrets, the CLI resolves each fromEnv variable on this machine, sends the values in a separate gRPC field (resolved_secrets, not in the manifest JSON), and the runtime encrypts them into session_secrets for the new session. If a referenced variable is missing, run fails with an actionable message. Ciphertext is deleted when the session reaches a terminal status. See Secrets.

Where values come from:

• Shell environment — export vars before run (for example export ANTHROPIC_API_KEY=...) and omit --env-file. This is the default path when CI, Docker, or your shell already injects credentials.
• --env-file / -e — load a dotenv-style file into the process before resolving secrets (repeatable). Variables already set in the shell are not overridden.
• gRPC callers — pass resolved_secrets on RunSession directly (no CLI env resolution).

The flag is optional: you only need -e when credentials live in a file rather than the current environment.

Flags

Examples

Detached run (default):

$ phrony run demo/echo-agent

Start in the background and attach:

$ phrony run demo/echo-agent --attach

Active deployment with explicit version (must be active):

$ phrony run demo/echo-agent@1.2.0
$ phrony run demo/echo-agent -v 1.2.0

With JSON input:

$ phrony run demo/echo-agent --input '{"city":"Oslo"}'

With secrets from the shell (no env file):

$ export ANTHROPIC_API_KEY=sk-...
$ phrony run demo/echo-agent

With secrets from a dotenv file:

$ phrony run demo/echo-agent -e .env
$ phrony run demo/echo-agent -e .env -e secrets.local.env

--input must be valid JSON. If omitted, the runtime uses an empty input object.

Output

Detached (default): one line with the new session id, for example session run_abc123 started. Resume later with sessions attach when status is awaiting_input.

Attached (--attach): the CLI streams session events: session started, assistant text, awaiting input (when applicable), then completion, failure, or cancellation. When stdin and stdout are TTYs, an interactive terminal UI is used; otherwise output is plain text. Ctrl+C closes your view only; use phrony sessions cancel to stop execution.

New sessions receive ids with a run_ prefix.

Human-in-the-loop (approval required)

When a policy requires approval before dispatch, the session moves to awaiting_approval and the runtime records a pending approval. No worker is invoked until an operator decides.

Detached runs (phrony run without --attach) pause in the background. Approve or reject from another terminal with phrony approvals; the session resumes without holding the interactive stream open.

Attached runs (--attach) print an approval_required event on stderr. You may detach with Ctrl+C and decide from another terminal with phrony approvals approve or reject (recommended), or send tool_approval on the same gRPC stream if your client implements it.

# Terminal 1
$ phrony run weather/weather-assistant --attach --input '{"message":"Send a severe alert for coastal Maine"}'

# Terminal 2 (while status is awaiting_approval)
$ phrony sessions ls --status awaiting_approval
$ phrony approvals list
$ phrony approvals approve <approval-id> --comment "verified"

See Human-in-the-loop approvals for quorum, comprehension, timeouts, and recovery after a runtime restart.