Why Compose is generated

Onebox does not read a Compose file you wrote. The contract is a declaration of what the application is; the Compose file, the container names and the routing labels are all derived from it.

Why the runtime is not yours to hand over

Under the ownership boundary, Onebox owns the runtime. Reading a runtime you wrote inverts that: you own it, and Onebox merely operates something it did not design and cannot fully reason about.

Concretely, that costs three things:

Two descriptions that can disagree. The Compose file would say one thing, the Onebox annotations another, and nothing would arbitrate.

No derivation. Onebox could not choose the container name, the volume name, the router rule or the network, because you already would have. So it could not guarantee they are consistent, collision-free, or stable across releases.

No honest defaults. strategy: rolling needs a health check to gate it. When the health check lives in a file Onebox merely reads, “is this rollout gated?” becomes a question rather than a fact.

What generation buys

• Derived, stable names. Workload containers use the uniform <app>-<component>-<replica> grammar, such as shop-web-1; managed services are onebox-<service>, such as onebox-postgres; persistent and provider resources include shop_default, onebox_postgres_data, onebox_services, and onebox-ingress. The application and service networks are declared external and created under Onebox’s ownership fence, so Compose cannot remove a live shared network during release teardown. A full ob destroy --volumes removes them; if an unmanaged endpoint remains attached, destruction stops without deleting Onebox’s recovery state or releasing host ownership. Once a resource exists its name cannot change without migration, and a foreign resource already holding a derived name is refused rather than adopted.
• Digest binding. The rendered Compose is bound into the plan, so what was reviewed is what executes.
• Refusals that mean something. strategy_ungated, route_collision, stateful_replicas are all statements about the generated runtime, which is the only thing that will actually run.
• Typed routing. Two workloads claiming the same entrypoint, protocol, hostname and path is route_collision, rather than a proxy that accepts both and routes to one with nothing saying which.

A workload name is its identity

Changing a workload’s key is a rename in the declaration but a replacement at runtime. Onebox starts and verifies the new workload, activates the release, and only then drains and removes the old workload. This ordering keeps a route rename from stopping the old endpoint before the new one can serve.

Persistent volumes follow the same identity rule: a renamed workload receives new derived volume names. Onebox does not guess that data should move between them. Move or reattach persistent data explicitly before treating a workload rename as complete.

You can still see it, and still leave

Generation is only acceptable because the output is inspectable and the exit is a command:

ob preview    # print the generated runtime, change nothing
ob eject      # write it out and hand it over, permanently

ob eject strips the overlay, so what lands in your repository is ordinary Compose — not Compose carrying Onebox labels you would then have to unpick — and your workloads are repointed at it with your comments intact.

And the escape hatch remains

A container Onebox cannot describe is adopted verbatim:

workloads:
  legacy:
    role: Daemon
    compose: docker-compose.yml#legacy

Refusals apply only where the referenced service contradicts something Onebox owns — extends, a fixed container_name, network_mode, labels in the onebox. or traefik. namespaces. See Adopt an existing Compose file.

The result is a contract that generates by default and defers on request, rather than one that can only do one of the two.