# Onebox

Production operations for the sole Onebox application on one server.
You describe what your application is in `ob.yml`; Onebox derives the Compose
runtime, names, routing, health gating, the proxy, and supporting services.
It connects over SSH. There is no deployment agent on the host.

> Use this file as a map of the Onebox documentation. Fetch any page as
> Markdown by appending `.md` to its URL. The CLI is the interface for people
> and agents alike: each executable leaf has a closed output protocol,
> errors are typed, and lifecycle mutations are idempotent under retry.

## Agent Resources

- [Markdown page export](https://onebox.run/start/first-deploy.md): Append `.md` to any docs page URL for clean Markdown.
- [Full documentation text](https://onebox.run/llms-full.txt): Every page concatenated, for one-shot ingestion.
- [Project file JSON Schema](https://onebox.run/onebox.run-v1.schema.json): The machine contract the loader enforces.
- [Sitemap](https://onebox.run/sitemap-index.xml): Crawler URL index.

## Operating Onebox from an agent

- Structured output (`--output human|json|ndjson`) is carried by these commands only: `ob abort`, `ob approve`, `ob audit`, `ob bootstrap`, `ob canonical`, `ob deploy`, `ob destroy`, `ob doctor`, `ob eject`, `ob exec`, `ob init`, `ob job plan`, `ob job run`, `ob logs`, `ob plan`, `ob preflight`, `ob preview`, `ob proxy apply`, `ob resume`, `ob rollback`, `ob schema`, `ob secrets edit`, `ob secrets list`, `ob secrets push`, `ob service apply`, `ob status`, `ob validate`, `ob version`. The permitted JSON/NDJSON modes differ by command; see the policy matrix.
- Read-only and safe at any time: `ob validate`, `ob canonical`, `ob preview`, `ob schema`, `ob status`, `ob doctor`, `ob audit`, `ob logs`, `ob plan`, `ob preflight`.
- Lifecycle operation commands: `ob deploy`, `ob rollback`, `ob resume`, `ob abort`, `ob bootstrap`, `ob destroy`, `ob job run`, `ob service apply`, `ob proxy apply`, `ob secrets push`; each enforces its own plan, confirmation, lock, and recovery requirements.
- `ob exec --reason ...` is an audited escape hatch. Nothing it changes belongs to a release; the journal stores only safe invocation metadata and a command digest, never command or output bytes.
- `ob approve` records a short-lived local confirmation bound to one exact plan. Its digest detects modification; it is not authenticated identity or an independently issued capability.
- A failure carries a stable `code` and separates read-only `diagnostic_command`, workflow `next_command`, and mutation-capable `resolving_command` guidance. Branch on the code, not the sentence. The full catalogue is at `/reference/errors.md`.

See `/reference/policies.md` for the schema identity of every structured document.

## Overview

- [Onebox](https://onebox.run/index.md): Landing page. What Onebox is, who it is for, and the fastest path into it.
  - Read when: Meeting Onebox for the first time

## Start here

- [Your first deploy](https://onebox.run/start/first-deploy.md): The full path — scaffold ob.yml, inspect what Onebox understood, plan, approve, deploy — with the plan and local-confirmation artifacts explained.
  - Read when: Deploying with Onebox for the first time
  - Read when: Understanding what a plan and an approval actually are
- [Install](https://onebox.run/start/install.md): Install ob from GitHub Releases, Homebrew, Scoop, or source, verify it, then confirm the runner.
  - Read when: Setting up Onebox on a new machine
  - Read when: Diagnosing a version or runner-compatibility refusal
- [Reading the file back](https://onebox.run/start/reading-it-back.md): ob validate, canonical, preview and schema — what each answers, and why origin annotations matter when reviewing a production configuration.
  - Read when: Reviewing a project file before a deploy
  - Read when: Working out where a value you did not write came from
- [What Onebox is](https://onebox.run/start/what-onebox-is.md): What Onebox owns on the box, what stays yours, and the scope it deliberately refuses. Read before deciding whether it fits.
  - Read when: Deciding whether Onebox fits a project
  - Read when: Explaining to someone else what Onebox does and does not own

## Guides

- [Add a database](https://onebox.run/guides/add-a-database.md): How to add Postgres, Redis or another built-in driver, wire the connection into your application's own variable names, and decide when to use a daemon workload instead.
  - Read when: Adding a database, cache or queue to a project
  - Read when: Renaming connection variables for an application that expects its own names
  - Read when: Deciding between a managed service and a daemon workload
- [Adopt an existing Compose file](https://onebox.run/guides/adopt-compose.md): How to adopt a container Onebox cannot describe, using compose: path#service, and which Compose constructs are refused because they contradict something Onebox owns.
  - Read when: Migrating an existing docker-compose.yml to Onebox
  - Read when: Running a container whose shape the project schema cannot express
  - Read when: Diagnosing a compose_* refusal
- [Eject](https://onebox.run/guides/eject.md): How ob eject works, what it writes, what it leaves behind, and why the exit exists as a first-class command.
  - Read when: Leaving Onebox, or evaluating the cost of doing so
  - Read when: Wanting to see the real Compose without the Onebox overlay
- [Handle secrets](https://onebox.run/guides/handle-secrets.md): How to declare plaintext and SOPS-encrypted environment files, which list a workload resolves, and what wins inside the container.
  - Read when: Adding secrets to a project
  - Read when: Working out why a container has the wrong value for a variable
  - Read when: Sharing one environment file across an upstream stack
- [Roll back a release](https://onebox.run/guides/roll-back.md): When to use rollback, resume and abort, what each guarantees, and why a data effect can make a rollback refuse.
  - Read when: A deploy failed or was interrupted
  - Read when: Deciding between resume, abort and rollback
  - Read when: Understanding why a rollback was refused
- [Run migrations safely](https://onebox.run/guides/run-migrations.md): How to declare a migration job, what data_effect controls, how job result evidence is captured and verified, and how the migration-backup policy gate works.
  - Read when: Adding a schema migration to a release
  - Read when: Understanding why a deploy halted before workload replacement
  - Read when: Configuring require_migration_backup for an environment
- [Schedule a job](https://onebox.run/guides/schedule-a-job.md): How to declare a scheduled job, why it runs from a host timer rather than a Onebox process, and which cron expressions are refused at load.
  - Read when: Adding a nightly or recurring task
  - Read when: Understanding why a cron expression was refused
  - Read when: Working out how a scheduled job resolves secrets with no Onebox process running

## Reference

- [CLI commands](https://onebox.run/reference/cli.md): Every ob command, its help text and its flags, taken from the binary itself.
  - Read when: Looking up what a command does, or which flags it takes
  - Read when: Deciding whether a command contacts the server or changes it
- [Service drivers](https://onebox.run/reference/drivers.md): The closed set of eleven service drivers, what Onebox provides for each, the connection parts they expose, and the known limitations.
  - Read when: Choosing a supporting service driver
  - Read when: Checking whether a driver exposes a particular connection part
  - Read when: Finding out why a driver name was refused
- [Error codes](https://onebox.run/reference/errors.md): Every typed failure code in the contract: the loader's validation codes and the CLI and engine's operation codes, all of which are reachable, and the lifecycle failure contract, where a row marked reserved is one no path raises yet.
  - Read when: A command failed and you have a code but not a cause
  - Read when: Branching on a failure programmatically instead of parsing a message
- [backup_targets](https://onebox.run/reference/fields/backup_targets.md): User-owned off-host S3-compatible repositories available to service protection policies. Accepted by the loader; not yet executable. [SCHEMA ONLY: the loader validates this and it is published in the JSON Schema, but the behaviour is not yet executable]
  - Read when: Evaluating the proposed protection layer
  - Read when: Understanding why Onebox refuses a backup target that shares the protected host
- [deployment](https://onebox.run/reference/fields/deployment.md): Release ordering, how many releases are retained for rollback, and the migration policy.
  - Read when: Changing release order, retention or migration gating
- [environments](https://onebox.run/reference/fields/environments.md): Where the application runs, the SSH target, per-environment overrides, and the policy governing deployment there.
  - Read when: Adding a staging or production environment
  - Read when: Requiring local confirmation, a minimum runner version, or a migration backup report
  - Read when: Working out which fields an environment override may change
- [external_services](https://onebox.run/reference/fields/external_services.md): Typed dependencies operated outside Onebox, whose lifecycle and protection stay external. Accepted by the loader; not yet executable. [SCHEMA ONLY: the loader validates this and it is published in the JSON Schema, but the behaviour is not yet executable]
  - Read when: Modelling an RDS, Neon, Supabase or Upstash dependency
- [hooks](https://onebox.run/reference/fields/hooks.md): Commands run at a lifecycle seam — bootstrap, pre_release, post_release, post_deploy — or keyed by a job name to replace that job's command.
  - Read when: Running a command around a deploy or a rollback
- [notifications](https://onebox.run/reference/fields/notifications.md): Named webhooks that receive selected operation outcomes.
  - Read when: Sending deploy outcomes to Slack, Discord or an incident tool
- [observability](https://onebox.run/reference/fields/observability.md): Declared logging, metric and alerting intent. Validated and planned, but the local engine runs nothing continuous for it. [INTENT ONLY: validated and carried into plans, but nothing continuous runs for it]
  - Read when: Recording observability intent that another system will act on
- [proxy](https://onebox.run/reference/fields/proxy.md): Who owns the ingress proxy, which image runs it, and how TLS is resolved.
  - Read when: Taking over the Traefik configuration, or turning routing off entirely
- [registries](https://onebox.run/reference/fields/registries.md): Named container registries and the local environment variables holding their credentials.
  - Read when: Pulling from a private registry
- [runtime](https://onebox.run/reference/fields/runtime.md): Project-wide environment files and the local environment-file assertions checked before the server is contacted.
  - Read when: Wiring up environment files or SOPS-encrypted entries
  - Read when: Requiring keys to be present before a deploy is attempted
- [services](https://onebox.run/reference/fields/services.md): Supporting services Onebox runs for you — the eleven built-in drivers, their versions, settings and persistence.
  - Read when: Adding a database, cache or queue
  - Read when: Deciding between a managed service and a daemon workload
- [Top level](https://onebox.run/reference/fields/top-level.md): Required keys, project-wide scalars, and the single-workload shorthand.
  - Read when: Starting a new project file
  - Read when: Working out which keys are required
- [verifications](https://onebox.run/reference/fields/verifications.md): What must be true before a release becomes current: external URLs, in-workload checks, or migration revision evidence.
  - Read when: Gating release activation on a health endpoint or a smoke test
- [workloads](https://onebox.run/reference/fields/workloads.md): The containers that are yours: their role, source, health, routing, prerequisites and container controls.
  - Read when: Declaring an application, worker, daemon or job
  - Read when: Choosing between image, build and compose as a workload source
  - Read when: Setting replicas, resources, volumes, published ports or drain behaviour
- [Naming conventions](https://onebox.run/reference/naming.md): How Onebox names things — casing, number, mood, and which words are reserved. Written down so a new field or flag has an answer before the review.
  - Read when: Adding a field, flag, command or error code and choosing what to call it
  - Read when: Wondering why two similar things are named differently
- [Policies](https://onebox.run/reference/policies.md): CalVer release identity, minimum runner and plan-schema policy, the executable plan and approval contracts, and the v1 evolution guarantees.
  - Read when: Pinning a minimum runner version for an environment
  - Read when: Understanding why a checkout build was refused
  - Read when: Checking what the v1 contract guarantees across upgrades
- [Project file](https://onebox.run/reference/project-file.md): Overview of the onebox.run/v1 project file — the block map, every scalar shorthand, and the two environment-value precedence rules.
  - Read when: Starting a new project file
  - Read when: Looking up which scalar shorthand forms are accepted
  - Read when: Working out which block a field belongs to

## Explanation

- [Evidence, not declaration](https://onebox.run/explanation/evidence-not-declaration.md): The principle that separates what you declared from what is observed — and how it shapes approval, tiers, drift, and structured output.
  - Read when: Understanding why an approval is separate from a plan
  - Read when: Understanding why declaring protection would not establish it
  - Read when: Designing something that has to report status honestly
- [Why Compose is generated](https://onebox.run/explanation/generated-compose.md): Compose is an artifact Onebox generates, not an input it reads. What that buys, and how you get out.
  - Read when: Wondering why you cannot hand Onebox a docker-compose.yml as the contract
- [The ownership boundary](https://onebox.run/explanation/ownership-boundary.md): The organising principle — you own your application containers, Onebox owns everything else — and the three design consequences that follow from it.
  - Read when: Understanding why the project file declares intent rather than describing containers
  - Read when: Explaining the product's design rationale
- [The safety envelope](https://onebox.run/explanation/safety-envelope.md): How Onebox makes execution resumable and reversible: application and host locks, fencing epochs, append-only journals, state-bound plans, and what each protects against.
  - Read when: Understanding what happens when a deploy is interrupted
  - Read when: Evaluating whether Onebox is safe to run from CI or an agent
  - Read when: Working out why a plan expired or a state binding went stale
- [What Onebox refuses](https://onebox.run/explanation/what-onebox-refuses.md): Onebox fails at load rather than silently weakening a declaration. The pattern, the refusals most likely to surprise you, and why force cannot override them.
  - Read when: A command refused and the reason is not obvious
  - Read when: Deciding whether a refusal is a bug or a design decision

## Status

- [Shipped vs proposed](https://onebox.run/status/capabilities.md): The honest inventory — every capability marked shipped, schema-only, or intent-only, with what each means for someone relying on it.
  - Read when: Deciding whether to rely on a capability
  - Read when: Reconciling what the editor autocompletes with what the engine does
  - Read when: Explaining to someone what Onebox does not do yet