0.2 Local mode and server mode

Included from Basic tier

After this you can: say which lane a command runs on, what the local lane can and cannot evidence, and choose the lane for the job.

Before you start — tick each one:

• Lesson 0.1 — Install and sign in (opschain learn 0.1)

In the GUI: nothing — local mode has no GUI; the server lane is the one the browser shows.

Every opschain command runs on one of two lanes. The local lane runs work from the repository in your current directory, on your machine, with no server. The server lane talks to an OpsChain server's API, which keeps the record. The two share one binary, one action-file format and most verbs — and differ in exactly the things that make a run evidence. This lesson draws that line so you always know which side of it you are on.

1. How a command picks its lane

The target resolves in this order:

1. the --server <url> flag;
2. the OPSCHAIN_SERVER environment variable;
3. your active context (set by opschain login, switched with opschain context use);
4. otherwise, local mode.

The global --local flag forces local mode for one invocation, ignoring the active context — the usual way to iterate in a repository while you are logged in to a server. See which lane you are on:

opschain context list

NAME           SERVER                       ACTIVE
local          (local mode)
opschain-dev   http://127.0.0.1:8443        *

With opschain-dev active, opschain runs list reads the server; opschain runs list --local reads your machine.

2. What the local lane can do

• Run actions off your working tree — opschain runs create change <action> --env dev --local snapshots your working copy (uncommitted edits included) and runs it attached to your terminal, exit code as outcome. --ref <git-ref> runs a clean commit instead. Lesson 2.1 starts here.
• Plan anything with --plan --local, and browse the catalog your repository defines with opschain actions list --local.
• Keep its own history: runs, steps, logs, artifacts and the property layers runs discovered, in a per-user SQLite store under your opschain home (<opschain home>/local/opschain.db) with its own generated keyset (local/keys.env) encrypting sensitive values at rest. Nothing to start, nothing to configure; opschain state doctor shows it and opschain state reset clears a project's slice (opschain docs storage, "Local mode").
• Resolve secrets through its own local secret store (opschain secret set|get|ls), so a secret-vault:// reference works unchanged on your laptop.
• Mount the bundled common pack and run its actions offline (lesson 2.4).

The target of a local run is an environment code from your repository's .opschain/config.yaml — not a node on any server.

3. What the local lane cannot do

• No users and no sign-in. Nothing records who ran a local run; there is no whoami, no identity, no access rules.
• No audit history. A local run keeps its own step transitions and logs, but the estate-wide audit events a server records (api:auth:login, api:projects:create, every approval decision — lesson 5.1) do not exist here.
• No estate. No nodes, templates, triggers, schedules, maintenance windows or runners — the nodes, properties show|edit|history, settings, triggers and admin families refuse by name without a server target.
• No approvals and no inbox. A wait: step prompts you in your terminal (or --approve-all answers it); approval policies, quorums and the approvals inbox are server things (lesson 2.3).
• No notifications, no chains across runs, and no change: steps that spawn a child change on another node (lesson 2.2) — local mode refuses those by name.
• No GUI. The browser shows a server.

The consequence that matters for the Academy: a local run is not evidence. The Academy agent decides whether an exercise was done by reading a server's state and audit events, so every verified exercise — including the authoring ones — ends with work on a server. --local is where you get it right first.

4. Choosing the lane

You want to…	Lane
write or fix an action and see it run now	local (--local)
prove a commit before pushing it	local (--local --ref <ref>)
run against a real node, with the record kept	server (lesson 3.1)
be approved, notified, audited, or verified	server
try a pack action offline	local (the bundled common pack)

Lessons 2.1–2.7 stay on the local lane; lesson 3.1 is where the same action first runs on a server.

Check yourself

• Name two things a --local run cannot produce that a server run does (hint: who ran it, and who was told).

What you learned

• A command's lane is --server, then OPSCHAIN_SERVER, then the active context, then local; --local forces local for one call.
• Local mode runs your working tree with its own store, keyset and secret store, and no server.
• Local mode has no users, no audit history, no estate, no approvals, no notifications and no GUI — so a local run is never evidence.
• Author and rehearse locally; run, govern and verify on a server.

Next: lesson 0.3 — Your tools: contexts, output formats, the API, the docs (opschain learn 0.3), or back to your track (opschain learn).