Your first worktree

This chapter takes one checkout from nothing to a running stack and back to a clean stop. The example is Hello Worktree: two Python 3 processes, no package installs, no accounts and no API keys.

Before you start

You need oberth on your PATH (Install oberth), Python 3, and the example directory, which ships in the repository.

git clone https://github.com/SheathedSharp/option-berth.git
cd option-berth/examples/hello-worktree

The checkout must live inside your home directory unless you pass --allow-outside-home; the engine refuses to manage a stack outside the home boundary by default.

Declare the stack

The example already carries an oberth.yaml. Read it before you run anything: it is the whole input.

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}

Two services. api asks for an automatically assigned port and a health check; worker has no port, starts after api, and receives the API's real address through ${api.url}. Nothing here is inferred from a running process.

In your own project, oberth init writes this file. oberth init draft lets an agent propose one; only a person runs oberth init adopt.

Start it and wait

oberth up --wait --json

--wait returns only when each service is really there: a bound listener for api, a passing /health, and a live process for the portless worker. A process that is still booting is not readiness, and a timeout is not success.

Read what is running

hello-worktree · main

api      running   :21730   health 200
worker   running   no port

2 services · manifest oberth.yaml

The port is this checkout's own: another worktree of the same repository gets a different one, because port: auto is assigned per run rather than remembered per project. no port is a fact, not a failure — the worker is observed through its run record.

Open the address that status prints to see the API answer with the port it actually bound. The same read as JSON is oberth status --json --brief, which is what an agent opens with.

Read the worker's log

worker: API health=200
worker: API health=200
worker: API health=200

--once reads the current run's log and returns. Without it, logs follows. When a service has already failed, --first-error gives the first error of the current run instead of the last screen of output.

Stop it

oberth down --force --json

down stops the services that this worktree started and hands their port reservations back. It does not touch another checkout, a normal user daemon, or processes the manifest never declared.

See the isolation for yourself

Create a second Git worktree of the same repository, enter examples/hello-worktree in both, and run up in each. The two API services get different ports. Run down in one; the other keeps running.