0.1 Install and sign in

Included from Basic tier

After this you can: put the opschain binary on your PATH, start a server of your own, create the first admin credential and sign in from the command line.

Before you start — the opschain binary on your PATH: lesson 0.0 puts it there (a package manager or a verified download — macOS, Linux and Windows), then come back here once opschain version answers. This lesson is the root of every track.

In the GUI: the root URL lands on the login screen; once in, the profile menu (top right) names your login with a chip for the provider it came from.

One binary, one server, one login. In this lesson you check the binary, bring up a server of your own, get its first administrator credential, and sign in — ending with opschain whoami telling you who the server thinks you are. That last command is what the Academy's first-contact exercise checks.

1. Check the binary

opschain version

opschain version v5.6.1 (commit 115eecc, built 2026-10-12T10:57:07Z)

The version shown above is the one this documentation ships inside — yours matches your binary. The commit and build timestamp here are illustrative: yours identify your exact build.

One binary carries everything: the CLI, the server (opschain server) and the runner (opschain runner). opschain doctor checks your host's capabilities (git is required; a container runtime unlocks optional step kinds).

2. Start a server

If you already have a server to work against, skip to the login in step 4. Otherwise bootstrap one locally:

opschain server configure --store postgres://opschain:secret@localhost:5432/opschain
opschain server start

server configure writes a complete runnable configuration to $OPSCHAIN_HOME/server/config.yaml — listen address (default 127.0.0.1:8443), store, blob root — plus generated key material in keys.env. Back those keys up: encrypted data is unrecoverable without them. For a fully annotated config covering every supported key:

opschain server configure --template > config.yaml

server start then brings up the whole system in one process: the API, the scheduler, the runner protocol — and the GUI, served at the root URL. Open http://127.0.0.1:8443/ in a browser and the web interface is there, talking to the same /api on the same port.

Choose the store deliberately. Without --store, the server runs on an embedded SQLite database. That zero-config store serves the GUI shell, the run/step/log API, node-path and event reads and local-lane development — but the identity and authorisation families (users, logins, policies) and the stored estate read models need PostgreSQL, and under SQLite they answer with exactly this guidance. A server on SQLite knows no users, so there is nobody to sign in as: give server configure a --store postgres://… DSN (a throwaway docker run postgres:18.6 is fine) or set store: in config.yaml. PostgreSQL 18.6 or newer is the minimum for a new deployment; 17 is supported as the previous major; 16 and older are refused at start-up with a message naming this policy. Give server start --tls-cert/--tls-key for HTTPS; plain HTTP is acceptable for loopback development only. opschain docs config is the full configuration reference.

The very first start of a fresh installation asks you to accept the LimePoint End User Licence Agreement: in a terminal the agreement is printed and you type accept; for an unattended install pass --confirm-eula or set eula: {accepted: true} in config.yaml. Read it any time with opschain eula. Acceptance is recorded once in the server's store and never asked again.

3. Your first admin credential

On a brand-new server (a store holding no users yet), the first start creates a local administrator for you: username admin, flagged break-glass, holding the Superuser policy. Its generated password is printed to the console exactly once:

opschain server: first boot: created local administrator "admin" (break-glass, superuser)
opschain server: initial admin password: … — store it now, it will not be shown again

Store it immediately (and rotate it at will with opschain admin users reset-password admin). For unattended installs set OPSCHAIN_BOOTSTRAP_ADMIN_PASSWORD in the server's environment and nothing is printed. (A server configured with security.posture: hardened never generates and prints a password: it requires that environment variable for the first boot and makes the admin rotate it on first login — see opschain docs identity.) From there you can create everyday users with opschain admin users create and change your own password with opschain passwd — no directory required; an enterprise directory plugs in later as a peer identity provider (lesson 7.5).

The opschain admin commands work with a plain opschain login session: the server authorises the caller through its access rules, which a superuser passes. A separate admin token is only for a server with no auth stack (the embedded store, started with --admin-token <value>); a PostgreSQL server refuses the token with a typed answer naming the alternatives — your own login, or a service-account API key (opschain tokens create) for automation.

4. Log in

opschain login --server http://127.0.0.1:8443 --username admin

You are prompted for your password (never stored); the CLI exchanges the credentials for an API token, stores the token in your OS keychain (or a permission-locked file with --no-keychain), and records a context for the server — activated immediately so subsequent commands target it (lesson 0.3). Already have a token? Use --token instead of --username.

Check who the server thinks you are:

opschain whoami

Server: http://127.0.0.1:8443
Identity: admin
Provider: local
Break-glass: true
Superuser: true

Provider names the identity provider the account belongs to (local or ldap:<code>) — useful when one username exists under more than one provider. Break-glass: true is the bootstrap administrator's flag; an everyday user does not carry it.

opschain logout removes the stored token and deactivates the context.

5. The verified version

Everything above is checkable from the server's own record: the login you just made was recorded as an api:auth:login event, and whoami is the server resolving your credential. The OpsChain Academy's first-contact exercise asks that same server both questions. Lesson 0.3 shows how to install and start the Academy agent; it needs a server with a PostgreSQL store, because a SQLite server knows no users.

Check yourself

• Does opschain whoami name you — and did you sign in after starting the exercise? The Academy's first-contact exercise reads the api:auth:login event raised since the attempt began, so a session from earlier does not count.
• What does opschain whoami print after you sign in, and which of its fields names the server you are talking to?
• Verified version: opschain academy runs the first-contact exercise against this lesson.

What you learned

• opschain version and opschain doctor tell you what you are running and what the host can do.
• server configure writes the config and keys; server start runs the API, scheduler, runner protocol and GUI in one process — on PostgreSQL if you want users.
• The first boot prints the admin password exactly once; store it and rotate it.
• opschain login records a context and a token; opschain whoami shows the identity the server resolves for it.

Next: lesson 0.2 — Local mode and server mode (opschain learn 0.2), or back to your track (opschain learn).