Install & sign up

This is the install path you actually run in your terminal, not a quickstart that hides the bytes. Every command below has been verified against the binary shipped at the head of main.

Install the CLI

$ npm i -g wos-core
   added 1 package in 4s

$ wos --version
wos          0.1.0
athena (L1)  0.1.0
nyx    (L2)  0.1.0

Node 20 or later. Tested on macOS, Linux, and Windows (PowerShell and WSL). The binary is a single self-contained ESM module; no peer dependencies are loaded at runtime.

Verify the binary

You should always verify before you run. The published binary is keyless-signed via Sigstore on the GitHub Actions runner that built it; the verification recipe is one command:

$ cosign verify-blob \
    --certificate-identity-regexp 'https://github.com/futami-worker-os/.*' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --signature wos.mjs.sig wos.mjs
✓  Verified OK

If verification fails, do not run the binary. Open a security issue at github.com/futami-worker-os/wos-core/issues with the failing fingerprint — we will respond within 24 hours. (Disclosure policy →)

Mint your first API token

Until wos signup lands as a CLI command (Week-1 hardening track), the canonical signup flow is one HTTP POST. The control plane mints the key, attaches a Stripe customer record, and signs the response in a single round-trip:

$ curl -s -X POST https://api.worker-os.com/api/v1/signup \
    -H 'Content-Type: application/json' \
    -d '{"email":"you@yourco.com"}' | jq

{
  "ok": true,
  "tenant_id": "a3b1c4d2-…",
  "stripe_customer_id": "cus_…",
  "api_key": "wos_sk_live_…",
  "api_key_id": "…",
  "api_key_prefix": "wos_sk_live_…",
  "created_at": "2026-05-10T12:00:00Z"
}

api_key is returned exactly once. Treat it like a Stripe restricted key: secret manager, never in source. The hash of the key (SHA-256) is what the control plane stores; the raw bytes never leave your terminal after this round-trip. There is no recovery path — if you lose the key, mint another.

First deploy

$ export WOS_API_TOKEN="wos_sk_live_…"
$ wos deploy examples/policy.yaml
✓  Deployed — kyc.tier2.jp.v3 v1
   dsl_hash:     b1946ac9···
   version:      1
   committed_at: 2026-05-10T12:00:00Z

If the response says idempotent: true, the dsl_hash you just shipped already has an active version on the control plane — nothing new was committed. This is the desired outcome of a CI re-run, not a failure.

If the response says Pre-flight lint failed, the local Athena compiler refused the bytes before they reached the wire. Run wos lint against the same file to see the structured errors.

What lives where

Surface	Variable / flag	Default
API token	`WOS_API_TOKEN` · `--token <key>`	(required for `wos deploy`)
Endpoint	`WOS_ENDPOINT` · `--endpoint <url>`	`https://api.worker-os.com`
Color	`NO_COLOR=1` · `FORCE_COLOR=1` · `--no-color`	TTY-detected
Output mode	`--json`	human-readable

wos --help is the source of truth — the table here is a digest, not a spec.

Self-hosted or air-gapped?

The CLI runs offline by design — wos lint and wos simulate never touch the network. For air-gapped operation including deploy, run your own control-plane endpoint and point WOS_ENDPOINT at it. The self-hosting recipe is on the Year-1 roadmap; see the changelog for status.

Where to go next

60-second tour — three commands against the example policy that ships in the repo.
Core concepts — what each layer does, with one verifiable artifact per concept.
For your compliance team — a page written for the CCO who needs to sign off on you running this.

60-second tour Core concepts