Make the loop your own.

Getting started

Connect your first repository and understand what setup prepares.

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

1. Open the application. Sign in with Not Organic to create your personal workspace.
2. Connect a repository. Use an HTTPS Git URL and, for a private repository, a scoped credential. Setup discovers the default branch.
3. Choose how to review. Autonomous is the default setup mode. Choose Supervised if you want blocking checkpoints during the repair loop.
4. Follow setup. Ephyra inspects the pinned commit, prepares configuration, discovers checks and records execution readiness. Read any blockers before expecting the loop to run.

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.

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

1. 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.
2. 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.
3. 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.

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.

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.

How a trail moves

Follow the evidence, checkpoints and outcomes of a repair.

1. SignalA reported problem
2. EvidenceObserved context
3. ReproA failing check
4. PatchA candidate fix
5. ProofRequired checks
6. LandingAn authorized write
7. WatchDeployment coverage
8. ClosedA recorded outcome

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

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 trail's evidence, activity, files and runs. A parked trail 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.

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.

# 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 trail 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.

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.

{
  "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.

{
  "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"
    }
  ]
}

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.

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.

{
  "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 trail, 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": {
    "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"
}

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.

{
  "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 trail 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.

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

Killing a trail 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:

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:

curl http://localhost:3000/healthz

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

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.

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