# Ephyra documentation

Pre-alpha · Updated 2026-11-08

Set up Ephyra with an agent, establish repository coverage, and configure policy, proof, deployment watch and self-hosting.

## Getting started

Connect your first repository and understand what setup prepares.

Ephyra turns production signals into quests: recorded work that moves from evidence to a failing reproduction, a
patch, proof, landing and watch. A quest keeps its history in Git.

Open the application. Sign in with Not Organic to create your personal workspace.

Connect a repository. Use an HTTPS Git URL and, for a private repository, a scoped credential. Setup discovers the default branch.

Choose how to review. Autonomous is the default setup mode. Choose Supervised if you want blocking checkpoints during the repair loop.

Follow setup. Ephyra inspects the pinned commit, prepares configuration, discovers checks and records execution readiness.
Read any blockers before expecting the loop to run.

A connection is the first step.A runnable workspace also needs model access, an isolated runner,
verified checks, applicable proof sources, and landing and watch integrations. Setup identifies what is missing.

Existing policy is retained. Prepared files include autonomy.md, thresholds.yaml,
intents/application.md and verification, evidence and recovery configuration. Generated prose and discovered commands still need
actual verification.

Configure workspace connections →

## Set up with an agent

Give an agent scoped setup access and establish useful observation before the first incident.

Give your coding agent Ephyra's auth.md instructions. They describe registration,
owner approval, credential renewal and the bootstrap API on the connected control plane. Use your own server's /auth.md when
self-hosting.

Ask your coding agent

Read https://ephyra.quest/auth.md and help me set up Ephyra for this repository.
Inspect the pinned repository, identify its important user journeys, and establish what Ephyra can observe and verify.
Ask me for missing expected behavior or connections. Report only checks and observations that actually happened.

Approve the exact repository and scopes

Identify the owner and repository. Give the agent your Not Organic DID, HTTPS Git URL and branch.
Keep repository credentials in Ephyra's settings or your credential store.

Review the claim. The agent gives you an approval link and a six-digit code. Sign in with the intended Not Organic
account, inspect the repository and requested scopes, then enter the code.

Let the agent establish context. Its separate credential can read setup, submit attributed findings and start supervised
setup within your existing grants. Each claim permits one setup run. Approval can connect the proposed repository when none is saved;
it cannot replace another connected repository.

The agent's scopes do not permit human checkpoint decisions, provider settings, spending grants, landing or arbitrary external messages.
Private repository credentials still need an owner-configured connection. Review or revoke agent access at any time.
Changing the connected repository or workspace invalidates the old access.

An explicit DID-bound profile.Inspired by WorkOS
auth.md, Ephyra supports anonymous registration followed by a claim bound to your Not Organic DID. It has no private pre-claim
capabilities. Email-based service_auth and external provider ID-JAG identity assertions are unsupported. Follow the metadata and
instructions published by your server.

Establish eyes, ears and a way to ask

Bootstrap inspects bounded documentation, manifests, CI, telemetry and deployment configuration at the pinned commit. It records source paths
and digests, proposes context to confirm, and assesses repository checks, telemetry, deployed revision, product context and contact coverage.

Observation coverage

Status	Meaning	

Observed	The assessment records an actual observation for this part of the setup.	

Configured	A connection is present; the corresponding observation is still missing.	

Missing	A required connection or capability is absent.	

Unknown	The available evidence cannot establish this coverage.	

Open your owner Inbox for setup requests before an incident exists. Ephyra asks about expected behavior and missing
connections, retains attributed answers, and reassesses when settings change and on scheduled checks. Those reassessments do not allocate a new
sandbox or call a paid model. Configuration requests resolve when their corresponding capability or observation is established.

If you explicitly enable an authenticated People bridge, Ephyra can also send a bundled notice to your configured owner contact.
Unchanged requests do not repeat the notice. A bridge acknowledgement records transport acceptance, not proof that a person read it.

A saved telemetry connection does not prove ingestion. A queried window with no exceptions does not prove that every user journey is
instrumented. Repository text, agent findings and owner answers are context; they cannot grant permissions or become passing proof.

Agent bootstrap API

Use the control-plane origin from /auth.md, an agent bearer credential and a stable Idempotency-Key for writes.
Reports must name the exact setup ID and repository head returned by the server.

Scoped agent setup endpoints

Endpoint	Purpose	

GET /v1/agent/setup	Read the recorded setup, coverage and open owner requests.	

POST /v1/agent/setup	Start supervised setup under existing workspace grants.	

POST /v1/agent/bootstrap/report	Submit bounded, attributed findings and proposed user journeys.	

POST /v1/agent/bootstrap/reassess	Refresh coverage without repeating provisioning.	

Keep ceremony tokens in memory and access credentials in a credential store. Never put them in repository files, journals, model prompts or
chat messages. Poll at the advertised interval, stop on an invalid grant, and obtain a new owner claim when needed.

## How a quest moves

Follow the evidence, checkpoints and outcomes of a repair.

SignalA reported problem

EvidenceObserved context

ReproA failing check

PatchA candidate fix

ProofRequired checks

LandingAn authorized write

WatchDeployment coverage

ClosedA recorded outcome

Triage decides whether a signal should become new work, join an existing quest or reach a person. Research records a hypothesis. Reproduction
establishes the failure before a plan becomes a patch.

The three review checkpoints

Checkpoint	What is reviewed	

A · Hypothesis	The proposed cause and its supporting evidence.	

B · Plan	The reproduced failure and the intended repair.	

C · Patch	The exact revision, diff and proof bundle.	

Approvals bind to the revision, head and proof that were reviewed. High and critical changes require a named human at C. Critical changes
require manual landing.

The console shows a quest's evidence, activity, files and runs. A parked quest carries a reason; an unavailable integration cannot create a
passing result. Closed repairs can contribute their observed reproduction as a regression probe.

## Workspace connections

Give the workspace the repository, models and evidence it can use.

Repository

The hosted HTTPS path supports GitHub, GitLab, Forgejo and other public HTTPS smart Git endpoints. Use a scoped
token where the repository needs authentication. SSH URLs, localhost and private-network endpoints are not supported by hosted account setup.

Changing the repository or branch selects a separate workspace, preserving earlier work. Recheck project-specific telemetry and knowledge
selections after switching.

Models and execution

Choose hosted Not Organic models or supported OpenAI, Anthropic or compatible model access. Saving a key checks
model discovery; it does not run a generation. The host must grant an isolated runner before an account can execute repairs.

Personal autonomous repairs require reported costs. A valid BYOK key alone does not establish cost reporting: an unknown-cost result blocks
continuation. See budgets and usage.

Telemetry and knowledge

Connect a scoped PostHog project for supported exception ingestion and landing-watch coverage. Provide a
deployment receipt URL to attribute the landed commit to production.

Optional Not Organic knowledge connections let you select readable resources and eligible read-only search tools. The account must grant the
exact source and tool. Those selections are checked again when evidence is used.

Keep credentials in connections.Repository tokens and model keys stay on the control plane. Put
observations in evidence and grant authority through account settings and policy.

## Policy and checkpoints

Set authority by area and understand draft, published and active policy.

Autonomy policy describes areas of the repository, their paths and risk, checkpoint behavior, allowed landing modes and watch
windows. Start with a narrow area whose checks you understand.

A supervised, low-risk area

# Autonomy policy

## defaults
mode: shadow
checkpoints: A=blocking B=blocking C=blocking
landing: trail_ref
watch: 2h

## area: documentation
paths: docs/**
risk: low
user_facing: false
Keep documentation accurate without changing application behavior.

This example keeps checkpoints blocking and permits a quest ref. Risk must reflect the real blast radius; lowering a label cannot replace required proof.

Draft → published → active

Workspace editing saves a draft. Publishing writes a policy Git ref. To put it into effect, an approver
explicitly activates the reviewed publication, checking its commit, content digest and previous active version.

Activation reloads Ephyra's policy. It does not deploy application code. Changed policy invalidates affected unfinished work and stale
approval. Already-authorized landing and watch retain their recorded authority.

When a save or activation has an uncertain outcome, refresh its recorded status before repeating it. An operation key identifies the original action.

## Proof requirements

Know which observations must exist before a repair can land.

Every repair needs a reproduction that fails before the patch and passes after it, test results, and the scope of its diff. Further
requirements depend on risk and whether the change affects a user or interface.

Evidence added by scope and risk

Scope	Additional requirements	

Any UI change	Story rendering and interaction results.	

Medium, high or critical	Executed regression and intent probes, plus bug review.	

Non-low UI	Visual differences and named approval of changed visuals.	

Non-low user-facing	A synthetic persona study.	

High or critical	Traffic replay and named-human checkpoint C approval.	

High/critical UI	A recording or terminal recording.	

High/critical user-facing	A completed real-respondent study.	

Critical	Manual landing; automatic and live landing are forbidden.	

Configure a trusted verification harness

Accepted-base .ephyra/proof.json selects UI and replay reporters. Declare the
complete harness and dependency closure in protectedPaths. Candidate modifications to that closure invalidate the verifier.

A repository reporter

{
"schema": 1,
"commands": [
{
"id": "stories",
"command": [
"bun",
"run",
"proof:stories"
],
"protectedPaths": [
"package.json",
"bun.lock",
"proof/**"
],
"kinds": [
"story_render",
"story_interaction"
]
}
]
}

The reporter must implement Ephyra's exact-bound JSON report contract and return actual executed observations. Merely adding this
configuration does not produce evidence. Repository reporters cannot supply persona or human-study provenance.

Reporter response contract

The command writes JSON to stdout and exits successfully only
after its checks complete. Read the binding from EPHYRA_PROOF_TRAIL, EPHYRA_PROOF_REV, EPHYRA_PROOF_BASE
and EPHYRA_PROOF_HEAD. Revision is a number.

Reporter response shape; illustrative values

{
"schema": 1,
"trailId": "EXACT_TRAIL_UUID",
"rev": 1,
"base": "EXACT_BASE_COMMIT",
"head": "EXACT_HEAD_COMMIT",
"items": [
{
"kind": "story_render",
"surface": "web",
"stories": [
"ACTUAL_STORY_ID"
],
"failed": [],
"uncovered": []
},
{
"kind": "story_interaction",
"surface": "web",
"stories": [
"ACTUAL_STORY_ID"
],
"failed": [],
"log": "ACTUAL_EXECUTION_LOG"
}
]
}

This illustrates the schema, not a passing run. Populate story IDs, failures, coverage and logs from the reporter's actual observations. Emit
only the evidence kinds granted to that command.

Script intent probes are supported. Other designed HTTP, trace and agent probe kinds need execution adapters. Missing probes, absent studies
and unavailable checks remain explicit blockers.

## Study evidence

Import actual study results through an operator grant or a signed provider.

Synthetic personas and real respondents are different proof items. A persona study stays synthetic and cannot satisfy a requirement
for human evidence.

Two receipt transports

Option	How evidence arrives	

Operator directory	An operator verifies a completed export and places its receipt in the protected receipt directory.	

Signed provider callback	A granted provider submits an Ed25519-signed receipt to POST /callbacks/proof.	

Both options require operator-owned absolute paths in EPHYRA_PROOF_RECEIPTS_DIR and EPHYRA_PROOF_TRUST_FILE. Grants
name the exact source, workspace and permitted evidence kinds. Account settings and repository code cannot create those grants.

A signed-source trust grant

{
"schema": 1,
"grants": [
{
"sourceId": "study-service",
"workspaces": [
"YOUR_WORKSPACE_ID"
],
"kinds": [
"persona_study",
"voxq_study",
"visual_approval"
],
"transport": "signed",
"publicKey": "ED25519_SPKI_PEM_PUBLIC_KEY"
}
]
}

For directory import, select transport: "directory" and omit publicKey. Unsigned directory receipts cannot be
submitted over HTTP.

Each completed receipt binds the quest, revision, base, head, provider operation and expiry. Conflicting, expired or unauthorized receipts are
rejected. These transports import completed evidence; automatic respondent dispatch additionally needs a host provider integration, a named spend
approval and remaining budget.

Receipt envelope and signing contract

Study receipt shape; replace all illustrative values

{
"receipt": {
"schema": 1,
"sourceId": "study-service",
"workspaceId": "YOUR_WORKSPACE_ID",
"trailId": "EXACT_TRAIL_UUID",
"rev": 1,
"base": "EXACT_BASE_COMMIT",
"head": "EXACT_HEAD_COMMIT",
"operationKey": "ACTUAL_PROVIDER_OPERATION",
"observedAt": "ISO_OBSERVATION_TIME",
"expiresAt": "ISO_EXPIRY_TIME",
"items": [
{
"kind": "persona_study",
"synthetic": true,
"study": "ACTUAL_STUDY_ID",
"runId": "ACTUAL_PROVIDER_RUN_ID",
"report": "ACTUAL_COMPLETED_REPORT"
}
]
},
"signature": "BASE64URL_ED25519_SIGNATURE"
}

Sign the UTF-8 bytes of canonicalJson(receipt), exported by @ephyra/core, with the provider's Ed25519 private key.
Encode the signature as unpadded base64url. Keep the private key at the provider; the server grant holds its public key.

For directory import, omit signature. In a source checkout, use proofReceiptPath(directory, receipt) from
@ephyra/server to determine the file path. A receipt remains immutable for that source, operation and exact
revision.

## Landing and watch

Attribute the remote write to an actual deployment and observe the outcome.

The stock personal HTTPS workflow writes the exact reviewed commit through the current account's repository authority, using
conditional remote-ref updates. Landing requires a deployment observer and telemetry coverage.

Publish a deployment receipt

Configure a public HTTPS endpoint that returns the actual deployed revision. It receives no account
credentials. The repository, branch and full SHA must match the saved connection and expected landed commit.

Deployment receipt response

{
"schema": 1,
"repository": "https://git.example.org/team/application.git",
"branch": "main",
"commit": "FULL_SHA1_OR_SHA256_COMMIT",
"deployedAt": "2026-11-08T12:00:00.000Z"
}

Replace the commit and timestamp with values from the deployment that actually happened. Use a URL without embedded credentials, query
parameters or a fragment.

Observe the complete window

Watch needs the deployed commit, applicable probes and complete attributed telemetry. PostHog computation
must cover the requested history and the required watch end. Retrieving an old cached result does not make its observations new.

A missing deployment, stale computation, truncated history or unavailable probe cannot establish a clean close. Regression and rollback
actions retain their own operation receipts; uncertain remote outcomes require reconciliation.

Native Radicle and Tangled proposal writes are host integrations. Closing a proposal is distinct from reverting deployed code, so canonical
landing and rollback need an explicit strategy.

## Budgets and usage

Bound cumulative work and keep unknown costs visible.

Each quest accumulates reported tokens, metered inference spend and executed wall time. Retrying or restarting does not reset those
counters. Waiting at a checkpoint does not consume execution time.

Deployment budget defaults

Setting	Default	

EPHYRA_TRAIL_TOKENS	2,000,000 reported tokens	

EPHYRA_TRAIL_WALLCLOCK_S	14,400 execution seconds	

EPHYRA_TRAIL_SPEND_MICROUSD	0; no metered inference allowance	

EPHYRA_REQUIRE_KNOWN_COST	false for deployment workspaces; always true for personal workspaces	

The operator must choose a metered allowance explicitly. Personal workspaces stop when a required cost is unknown. Some BYOK providers do not
return a reconciled cost, even when the request succeeds.

Sandbox resource grants are separate from inference budgets. A model allowance does not cap cloud VM billing. CLI providers cannot enforce
limits their interfaces do not expose; reported usage is recorded after execution.

Stopping and recovery

Stopping a quest aborts active work and attempts to destroy its runner handles. Stop receipts distinguish
confirmed destruction, pending allocation and uncertain cleanup. One fenced worker owns a durable workspace; stale work cannot adopt a new
owner's authority.

Pending or ambiguous external operations require reconciliation. Recovery restores recorded work without blindly repeating a provider call or
remote write.

## Self-hosting

Boot a local development API, then add durable state and account authority.

Local development

From an Ephyra source checkout, install Bun 1.4 and Git. Build the console and generate a random service token:

Start the development server

bun install
bun run --filter @ephyra/console build

export EPHYRA_API_TOKEN="$(bun -e 'console.log(crypto.randomUUID()+crypto.randomUUID())')"
EPHYRA_DATA_DIR="$PWD/.ephyra-local" bun run --filter @ephyra/server start

In another shell with the token available, check health and authenticated API access:

Check the local API

curl http://localhost:3000/healthz

curl \
-H "Authorization: Bearer $EPHYRA_API_TOKEN" \
-H "X-Ephyra-Principal: local-dev" \
http://localhost:3000/v1/trails

This is memory mode.Without Convex configuration, workflow and account state are development-only and
are lost on restart. This command does not configure a personal account repair workflow.

Durable hosting

Deploy apps/server/convex to your own Convex project. Set the same EPHYRA_CONVEX_SECRET
there and on the server, then configure that deployment's CONVEX_URL. Persist EPHYRA_DATA_DIR for Git journals,
repository mirrors and local operation records.

Browser sign-in needs EPHYRA_PUBLIC_ORIGIN, EPHYRA_SESSION_KEY (32 random bytes encoded as base64 or base64url), and
approver configuration. Generate credentials for your installation and keep them outside Git.

Hosted account execution also needs explicit runner and account grants. Self-hosted CLI agents require their CLI in the runner image. Native
forge transports and remote Amp identity verification require host integration.

## API and availability

Find the public API entry points and current integration boundaries.

The control-plane API is served by your Ephyra server, separately from this documentation site. Service-token requests use
Authorization: Bearer … and X-Ephyra-Principal. Personal account routes require an authenticated human session.

Useful API routes

Route	Purpose	

GET /healthz	Store health and the exported release revision.	

GET /v1/me	Authenticated identity and decision permissions.	

GET /v1/trails · GET /v1/inbox	Recorded quest state and review requests.	

GET /v1/runs · GET /v1/usage	Agent activity and recorded usage.	

GET /v1/policy/active	The active policy receipt, or null.	

GET /v1/ops	Worker ownership, dead jobs and reconciliation state.	

Some mutating endpoints require operation keys. Account writes also require current account, workspace and version bindings. Check the
recorded outcome before repeating an uncertain action. The service token cannot approve a personal human checkpoint when sign-in is required.

What needs configuration

Supported paths include account-scoped HTTPS repositories, selected model access, recorded setup, script
probes, trusted proof receipts, conditional Git landing, and attributed PostHog watch. Each path still needs its declared capabilities and
permissions.

Native proposal transports, remote Amp reports and respondent dispatch need host integrations. Other designed intent probe types and proposed
hunting workflows are not advertised as configured capabilities. A healthy server or passing local test does not establish a paid provider run or
a production repair.

Open your workspace ↗Read the security policy