Fleet

Dev mode

One server on SQLite, with the same APIs and security as a cluster.

For: cluster operators.

Use dev mode to run a local server and join a development node. Review its sandbox exception before using shell or write sessions.

Dev mode runs management, the edge and an embedded Temporal in one process on SQLite. It has the same APIs and the same security as a cluster, so what works in dev mode works in production, with one exception: its shell and write sessions may run without a sandbox.

Terminal
oz0 server start --dev --data-dir .oz0/dev

The first start in a data directory creates:

  • a cluster named dev with its master key and CAs,
  • the tenant default,
  • an operator context at .oz0/dev/operator/context.json,
  • a reusable join token at .oz0/dev/join-token (1,000 uses and 30 days, the most a token may have; the next start makes a new one when it is used up or expired),
  • the console's admin account, with its password in .oz0/dev/admin-password.

Without --data-dir, everything lives in a temporary directory that is removed when the server stops.

The operator's certificate is valid for 90 days. Each start issues a new one when it is missing or has less than 30 days left, so a dev data directory keeps working.

Join a node to it

Terminal
export OZ0_CONTEXT=.oz0/dev/operator/context.json
OZ0_JOIN_TOKEN="$(cat .oz0/dev/join-token)" oz0-node join --server https://127.0.0.1:7443
oz0-node run --runtime-bundle "$OZ0_RUNTIME_BUNDLE"

In a third terminal, check that the node is there and run something:

Terminal
export OZ0_CONTEXT=.oz0/dev/operator/context.json
oz0 node list
oz0 job run --task-queue oz0.default --workflow HelloWorkflow --input '"you"'

No sandbox floor

A dev server differs from a cluster in one rule. In a cluster, every harness session that can run a shell or write files runs on a node with sandbox tier 1, or on a node a tenant admin opted out. A dev server is one machine, often without bubblewrap, so it lets every node run such sessions, without a sandbox on a node that has no tier 1, rather than fail a developer's job. It says so where it starts, in the log and in oz0 dev's output:

Sandbox: this dev server runs shell and write harness sessions on any of its nodes, without a sandbox on a node that has no sandbox tier 1; do not trust it as production. ...

The console's Nodes page shows the same note. Jobs that ran such a session without a sandbox show tier 0 and the node, as on a cluster. Do not run work you would not run in your own shell on a dev server. oz0 server start --dev --sandbox-floor holds a dev server to the cluster's rule, to try it out.

Ports in dev mode

Dev mode binds to 127.0.0.1 unless you pass --ip.

PortWhat
7233The edge's Temporal proxy, for nodes
7443The edge's HTTPS API: join, control stream, artifacts, LLM gateway, runtime API
7234The embedded Temporal frontend (only the edge uses it)
8233The Temporal console; --temporal-ui-port 0 turns it off
8443Management: the console and the admin API, for the CLI

oz0 dev for plugin authors

If you are building a plugin, oz0 dev is quicker: it starts a dev server on free ports, joins a node, installs your plugin from its working tree and reinstalls it on every change. See Develop and test.

Copyright © 2026