Account & Activation

Zero-config activation, CI and headless machines, what happens offline, and what revoking a device actually does.

Activation provisions a machine under your account. In normal use you never run it by hand — it's folded into your first encrypt.

Zero-config activation

The first protect / protect-model / build call on a new machine signs you in (opens a browser) and activates the machine in one step, then encrypts:

shell

magiclock protect app.py   # first run: sign in + activate, then encrypt
magiclock protect app.py   # every run after: encrypts immediately, no prompts

Explicit commands

You'll rarely need these directly, but they're there when you do:

shell

magiclock activate                  # authenticate (opens a browser) + provision this machine
magiclock activate --no-browser     # print a link + code instead of opening a browser
magiclock status                    # this machine's account + activation state
magiclock status --offline          # same, without a live server round-trip
magiclock deactivate                # remove this machine (frees its seat server-side by default)
magiclock deactivate --local-only   # remove it locally only, without touching the server

CI and headless machines

Pass a portal-minted token instead of opening a browser:

shell

export MAGICLOCK_TOKEN=<token-from-your-account-portal>
magiclock protect app.py            # provisions non-interactively, then encrypts

A release build of the CLI also bakes in the license server's URL, so MAGICLOCK_SERVER is only needed if you're pointing at something other than the default.

Environment variables

Variable	Used by	Purpose
`MAGICLOCK_TOKEN`	`activate`, and the auto-activation on first encrypt	Bearer token for non-interactive sign-in.
`MAGICLOCK_SERVER`	`activate`	Overrides the license server URL (rarely needed).
`MAGICLOCK_PASSPHRASE`	`protect`/`protect-model`/`run`	Non-interactive passphrase for `--passphrase` artifacts (portable, or two-factor with `--bind-machine`).
`MAGICLOCK_DECRYPT_KEY`	`run`	Alternative to `run --key` for portable `--emit-key` artifacts.
`MAGICLOCK_NO_BROWSER`	any auth flow	Suppresses auto-opening a browser (also auto-detected on headless Linux).
`MAGICLOCK_NO_OS_KEYRING`	all commands	Skips the extra OS-keyring wrap on the local credential store — useful in minimal containers without a keyring service.
`MAGICLOCK_VAULT`	all commands	Where this machine's activation lives (default `~/.magiclock/vault`). Same as `--vault`. Set it to keep the vault on a mounted volume, or to run more than one account on one machine.
`MAGICLOCK_GATE_DIR`	running cloud-controlled artifacts	Where the signed approvals of `--web-gate` artifacts are cached (default `~/.magiclock/gate`). Point it at a writable path on read-only or ephemeral filesystems.

What happens when you're offline

Encrypting (protect/protect-model/build) checks in with the license server every time. If that check succeeds, you're good. If the network is down:

Situation	Result
Server reachable, license valid	Encrypts normally.
Server unreachable, for any reason	Blocked until you're back online.
Server reachable and explicitly denies (device revoked, plan expired/canceled)	Blocked immediately — this is never given grace, online or offline.

Decrypting and magiclock run are never affected by any of this. They read only the local, already-activated vault — no network call, no server dependency, ever. This is true whether the machine is online, offline, or has never been online since activation.

Revocation and deactivation

magiclock deactivate (without --local-only) tells the server to release this machine's seat and blocks it from encrypting anything new. It does not reach back into artifacts already produced on that machine — those keep decrypting, because decryption never consults the server or any revocation list. If a machine is lost or compromised, deactivating it stops it from producing new protected artifacts under your account; it doesn't retroactively revoke files it already produced.

What's next

Security Model covers what the runtime gate checks and why decrypt-side revocation isn't part of the design.
CLI Reference has the full flag list for every command on this page.

PreviousCloud Control NextCLI Reference