Declare what should run

Every fact starts with a declaration. oberth.yaml says what this checkout runs; a person confirms it, and the engine never infers a start command from a process it happened to see.

Start from the worktree

oberth init generates a reviewable starter from the current checkout. Listening ports and declarations found in project files appear only as comments, left for a person to decide. A failed listener scan does not abort init: the comment says listening unknown with the observation code and the next step, because “could not look” is not “nothing is listening”.

generate and preview

oberth init
oberth init --dry-run

--dry-run previews without writing; --json is the machine shape. A failed scan still leaves the project's own declarations and an entry shape to copy.

Let an agent draft, a person adopt

draft and adopt

oberth init draft claude
oberth init adopt --dry-run --diff

init draft [agent] asks the configured local agent for a manifest. option-berth judges nothing, goes online for nothing and writes nothing: success only produces a draft, archived by default under ~/.option-berth/drafts/. init adopt is the step that writes oberth.yaml. An existing manifest needs an explicit --replace or --merge; --dry-run and --diff show the result first. A draft is not authorization.

The smallest manifest

oberth.yaml · hello-worktree

name: hello-worktree
services:
  - name: api
    cmd: python3 -u api.py
    port: auto
    health: /health
  - name: worker
    cmd: python3 -u worker.py
    depends_on: [api]
    env:
      API_URL: ${api.url}

The fields in the smallest manifest
Field	What it promises
`name`	The project group. Two worktrees of the same repository publish as `name` and `name@worktree`.
`services[].cmd`	The long-running command, split into argv without a hidden shell.
`port`	A fixed number, or `auto` so the engine allocates one per run and injects `PORT`.
`health`	An HTTP path, a TCP port or a command. A service that opens its port before its protocol is ready uses the command form.
`depends_on`	Start order and readiness waiting: a dependent starts only after its dependency is ready.
`env`	Literal values and references such as `${api.url}`, expanded from this worktree's address book.

Fields that change behavior

prepare: and prepare_inputs:: A prerequisite command runs before the long-running cmd:. When the declared inputs are unchanged since the last success, the next up skips it instead of reinstalling dependencies.
sources:: The files that tell whether the process runs the current code. status publishes code_changed_since_start; sources: [] turns the check off for a service that hot-reloads.
ready_timeout:: The service's own readiness budget (Go duration, default 30s). Successors and up --wait use it; prepare: does not count against it.
env_file:: A dotenv-style file read at start and never written back. Relative paths resolve from the manifest directory, so several worktrees can share one file outside the checkout.
machine:: A dependency this project observes but never starts or stops: a database, middleware, a service someone else owns.
workspace:: An address reference to a service in another checkout. It supplies ${name.url} and takes no part in start, stop or depends_on.

What the manifest may not do

Edit this page