Select the project
The slug resolves a registered project. Confirm session.cwd matches the repository you intend to operate before continuing.
Skip to documentation content01 02 03
Operator documentation
Operate the control plane with current evidence.
Target the intended project and TUI, inspect live state, then diagnose, change, and verify through the visible UNAXIS workflow.
Getting started
Start with state, not assumptions.
Run these commands in order. They identify registered projects, compare running control planes, and show the current session and operation stack. Replace <project-slug> with the exact slug returned by project list; this example explicitly targets the development TUI.
Safe starting pointThese commands inspect state. Lifecycle, deploy, proxy, and database commands can mutate it and require their own safeguards.
PowerShell · dev TUI
unaxis project list
unaxis version --compare
unaxis <project-slug> status --dev
unaxis <project-slug> session --json --dev
unaxis <project-slug> stack --json --dev- 01
Resolve the project
Run project list and choose the registered slug. Use that exact slug in every project-scoped example; confirm session.cwd matches the repository you intend to operate.
The registered root and session cwd agree. - 02
Choose the control plane
Compare the running TUIs, then keep --dev or --prod explicit on every project-scoped command. The example targets development.
The intended TUI responds to status. - 03
Inspect before acting
Read session and stack JSON. Stop if the cwd or environment is unexpected, or if active or queued work would conflict.
The session and operation state are understood.
Read the final sentinel
Project-scoped IPC output ends with __UNAXIS_EXIT__:<code>:<label>. A final 0:ok is complete. 3:queued is accepted but unfinished; inspect the project stack until the operation reaches a terminal state. On the installed Windows client, the final sentinel is authoritative when valid output is followed by a contradictory shell exit code.
CLI and targeting
Scope the project and control plane explicitly.
The project slug and TUI target answer different questions. Keep both visible in every live control-plane command.
Project-scoped grammar
Registered project commands begin with the slug returned by project list. Global discovery commands are the exception and do not use a project slug.
unaxis <project-slug> <command> [arguments] [options] --dev|--prodSelect the TUI
Append --dev for the development control plane or--prod for the installed production control plane. Do not rely on implicit targeting when both may run.
Select the output mode
Use --json only on commands that support it. A--bg operation is queued, not complete; follow the project stack to a terminal result.
| Family | Start here | Effect |
|---|---|---|
| Discovery | unaxis project listunaxis --helpunaxis --schemaunaxis version --compare | Read-only |
| Control-plane state | unaxis <project-slug> status --devunaxis <project-slug> session --json --devunaxis <project-slug> stack --json --dev | Read-only |
| Zones and logs | unaxis <project-slug> zones list --json --devunaxis <project-slug> zone docs status --devunaxis <project-slug> zone docs logs --tail 120 --dev | Mixed |
| Environments | unaxis <project-slug> env list --json --devunaxis <project-slug> env ping <name> --dev | Mixed |
| Guard and follow work | unaxis <project-slug> preflight edit --zone <key> --watch --label "<intent>" --devunaxis <project-slug> stacks --tail 8 --dev | Mixed |
| Zone lifecycle | unaxis <project-slug> zone <key> build --bg --json --dev | Changes state |
Discover, then reconcile
unaxis --help is the installed human reference and unaxis --schema exposes a structured subset. Neither is exhaustive today, so verify state-changing grammar against the relevant guide and current source before operating.
Zones lifecycle
Inspect, develop, ship, and verify one zone.
This routine loop assumes the target zone already exists. Start with session and stack state, keep the TUI target explicit, and stop when another operation would conflict.
- 01Read-only
Inspect the existing zone
Confirm the zone exists, read its production status, and keep log reads bounded before changing runtime state.
unaxis <project-slug> zones list --json --dev unaxis <project-slug> zone <key> status --dev unaxis <project-slug> zone <key> logs --tail 120 --dev - 02Changes state
Open and close development
Use preflight for a guarded edit, inspect the explicit dev container, then stop it and end the watch after validation.
unaxis <project-slug> preflight edit --zone <key> --watch --label "edit <key>" --dev unaxis <project-slug> zone <key> dev logs --tail 120 --dev unaxis <project-slug> zone <key> dev stop --dev unaxis <project-slug> watch end --dev - 03Changes state
Ship source once
Queue one build at a time. Build is the complete ship path: build, push, pull, force-recreate, and proxy reload.
unaxis <project-slug> zone <key> build --bg --json --dev unaxis <project-slug> stacks --tail 8 --dev unaxis <project-slug> zone <key> status --dev
Queued is not complete
A final 3:queued means the control plane accepted the operation. Follow stacks until the work reaches a terminal result, then verify zone status, bounded logs, image provenance, and the changed behavior with a cache-busting browser request. Do not run deploy automatically after a successful build; build already deploys.
| Action | Command | Effect | Use when |
|---|---|---|---|
| Restart development | unaxis <project-slug> zone <key> dev restart --dev | Changes state | Restart only the explicit zone dev container after an edit requires it. |
| Rebuild without cache | unaxis <project-slug> zone <key> rebuild --bg --json --dev | Changes state | Run the full ship path without build cache; use only when evidence points to stale build layers. |
| Redeploy an image | unaxis <project-slug> zone <key> deploy --bg --json --dev | Changes state | Pull and recreate from an existing image without rebuilding source. |
| Repair zone wiring | unaxis <project-slug> zone <key> doctor --dev | Changes config | Patch Compose when needed, reconcile the proxy route, and verify or register NPM state. |
| Delete a zone | unaxis <project-slug> zone <key> delete --confirm --dev | Destructive | Require explicit approval; this removes runtime, source, registry, route, and proxy-host state. |
Creation and deletion are separate multi-system operations.
Do not create a replacement zone to work around a broken existing target. Deletion requires --confirm and explicit approval. Its exact terminal-sentinel behavior is TBD while the current IPC handler and delete helper return shapes are reconciled; independently verify every removed surface.
Environments
Target the control plane, then name the infrastructure node.
A zone is an application deployment. An environment is the infrastructure boundary that exposes agent-backed container, stack, log, event, and security evidence.
Keep every boundary visible
This guide uses a registered project slug, the development TUI, and an explicit environment name. Replace each placeholder only after reading the live session and environment list.
unaxis <project-slug> env <subcommand> [arguments] [options] --dev|--prod- 01Read-only
Separate the three targets
The project slug resolves the repository, --dev or --prod selects the running TUI, and the environment name selects an infrastructure node behind that control plane.
unaxis <project-slug> session --json --dev unaxis <project-slug> env list --json --dev - 02Read-only
Inspect one node explicitly
Name the environment even when a command permits an implicit default. Containers shows unt_* workloads unless --all is added; stacks groups every container by its Compose project label.
unaxis <project-slug> env containers <environment> --dev unaxis <project-slug> env stacks <environment> --dev - 03Read-only
Collect bounded evidence
Tail a named container, inspect a numeric event window, or audit container posture without changing lifecycle state. Keep internal output scoped to the investigation.
unaxis <project-slug> env logs <environment> <container> --tail 120 --dev unaxis <project-slug> env events <environment> --since 600 --dev unaxis <project-slug> env security <environment> --json --dev
Default does not mean exclusive
All registered environments can be live at the same time. The default target only preselects where the zone wizard deploys; name the environment explicitly for operator commands. Also name it on env ping: the current parser can otherwise interpret a trailing --dev as the optional environment name.
| Intent | Command | Effect | Operator note |
|---|---|---|---|
| Discover registered nodes | unaxis <project-slug> env list --json --dev | Read-only | Use the returned names for every later environment command. |
| Refresh agent health | unaxis <project-slug> env ping <environment> --dev | Writes metadata | Probes the named agent and persists status, version, and last-seen metadata in the control database. |
| Show the full Docker host | unaxis <project-slug> env containers <environment> --all --dev | Read-only | Expands beyond the default unt_* filter; treat the wider inventory as sensitive evidence. |
| Audit image history | unaxis <project-slug> env audit-image <image> <environment> --json --dev | Read-only | Runs a heuristic layer-history scan. Review findings manually; the result is not proof that an image is safe. |
| Update an environment agent | unaxis <project-slug> env update <environment> --dev | Changes state | Replaces the agent through its update path. Keep it outside an inspection-only workflow. |
Database instances and snapshots
Name the target, create the right recovery point, and verify beyond the sentinel.
Core holds platform data. Runtime instances are independent stacks. Their snapshot format is shared, but their outage and recovery risks are not.
Keep Core and instances explicit
Use unscoped database capture commands for Core and the db instance <target> family for runtime instances. Confirm the project, TUI, target slug, and empty operation stack before any recovery action.
unaxis <project-slug> db <subcommand> [target] [options] --dev- 01Read-only
Identify the protected target
Core is the platform Supabase stack. Runtime instances are separately registered stacks with their own slugs and recovery history. Use the plain list first; JSON registry output contains secrets.
unaxis <project-slug> db instances --dev unaxis <project-slug> db instance <target> status --dev unaxis <project-slug> db instance <target> logs --tail 120 --dev - 02Writes recovery data
Choose the recovery artifact
A quick Core backup is a database-only pg_dump on the Core data volume. A full snapshot adds schema, Storage, redacted environment, Compose, metadata, and restore helpers, then attempts an archive beside the raw bundle. Capture is sequential, not an integrity test.
unaxis <project-slug> db backup --reason "before <change>" --dev unaxis <project-slug> db snapshot --dev unaxis <project-slug> db instance <target> snapshot --bg --json --dev - 03Mixed
Inspect every result
Follow a queued snapshot to terminal state, then read its full output. Listing is read-only; verify probes Compose health and writes derived health and status metadata, but does not validate recovered data or Storage.
unaxis <project-slug> stacks --tail 8 --dev unaxis <project-slug> db snapshots --dev unaxis <project-slug> db instance <target> snapshots --dev unaxis <project-slug> db instance <target> verify --dev
Prefer explicit instance commands
The current top-level db snapshot --slug and db snapshots --slug handlers can fall back to Core when a runtime slug does not resolve, so those forms are intentionally omitted. The structured schema is also incomplete; use installed help and current source together.
| Intent | Command | Effect | Operator note |
|---|---|---|---|
| Inspect runtime instances | unaxis <project-slug> db instances --dev | Read-only | Lists registered runtime instances. Core is a separate protected target and is not a runtime registry entry. |
| Create a quick Core backup | unaxis <project-slug> db backup --reason "<reason>" --dev | Writes backup | Writes a compressed SQL dump inside the Core database volume. It excludes Storage and metadata and is not a full restore bundle or off-volume protection. |
| Snapshot Core | unaxis <project-slug> db snapshot --dev | Writes bundle | Captures the raw full-bundle directory and normally an adjacent archive. Review Storage-copy and archive lines; warnings can coexist with a successful result. |
| Snapshot one instance | unaxis <project-slug> db instance <target> snapshot --bg --json --dev | Writes bundle | Uses the explicit instance family. A queued response is unfinished; follow the project stack and retain the raw bundle directory. |
| Verify one instance | unaxis <project-slug> db instance <target> verify --dev | Writes metadata | Checks container state and health, then synchronizes registry status. It does not verify snapshot integrity, database contents, migrations, Storage, or application behavior. |
| Restore one instance | unaxis <project-slug> db instance <target> restore --bundle "<bundle-directory>" --dev | Destructive | Stops the target, replaces database and Storage content, and restarts it. Require approval, a fresh full snapshot, and independent data verification. |
| Restore Core | unaxis <project-slug> db restore --bundle "<core-bundle-directory>" --dev | Destructive | Interrupts the platform stack. Confirm that bundle metadata identifies Core, record the expected outage, and obtain explicit approval before invoking it. |
Restore has no confirmation gate or automatic safety snapshot.
Record the exact target and raw bundle directory, create a fresh full snapshot, and obtain explicit human approval. Read every restore line: database or Storage failures can be warnings before a final success result. Then verify containers, bounded logs, expected data, Storage, and application behavior while retaining the source bundle. Core bundle-path discovery in the CLI is TBD; do not guess it. Treat DB JSON, DB views, MCP output, logs, and snapshot bundles as confidential even when an environment file is redacted.
Build, routing, and troubleshooting
Build once, trace the route, and treat 502s as evidence.
Follow background work to a terminal result, then verify the zone runtime, proxy chain, NPM edge, and public response before retrying or escalating.
Resolve the slug before copying commands
Use project list as the source of truth for the project slug. A zone build changes runtime state and should run through the visible stack with a single target zone and TUI.
unaxis <project-slug> zone <key> build --bg --json --dev- 01Read-only
Establish the operation lane
Confirm the registered project, intended TUI, current stack, target zone, and logs before queuing work. A running dev TUI is not proof that the public overlay is valid.
unaxis project list unaxis <project-slug> session --json --dev unaxis <project-slug> stack --json --dev unaxis <project-slug> zone <key> status --dev unaxis <project-slug> zone <key> logs --tail 120 --dev - 02Diagnostic
Diagnose before rebuilding
Build checks should explain the failure mode. Use bounded tails, build reachability probes, and memory snapshots before deciding that source, cache, routing, or capacity is the fix.
unaxis <project-slug> stacks --tail 12 --dev unaxis <project-slug> build-doctor <key> --dev unaxis <project-slug> build-mem --dev unaxis <project-slug> logs proxy --tail 120 --dev - 03Changes state
Ship once and prove it
Queue one build at a time. A build is the full ship path: build, push, pull, force-recreate, and proxy reload. Follow the stack to terminal state before judging the public URL.
unaxis <project-slug> preflight edit --zone <key> --watch --label "update <key>" --dev unaxis <project-slug> zone <key> build --bg --json --dev unaxis <project-slug> stacks --tail 12 --dev unaxis <project-slug> env containers <environment> --json --dev https://<key>.unenter.live/?cb=<unique-value>
Build is already the deploy
zone <key> build runs the complete ship path: build, push, pull, force-recreate, and proxy reload. Use deploy only when an existing image should be redeployed without rebuilding, or when the build/push leg succeeded but the deploy leg failed.
| Intent | Command | Effect | Operator note |
|---|---|---|---|
| Follow visible work | unaxis <project-slug> stacks --tail 12 --dev | Read-only | Shows all stack items with bounded output tails. Use it after any queued operation and before starting a competing lifecycle action. |
| Queue a complete ship | unaxis <project-slug> zone <key> build --bg --json --dev | Changes state | Builds, pushes, pulls, force-recreates the container, and reloads the proxy. A queued sentinel is accepted work, not success. |
| Rebuild without cache | unaxis <project-slug> zone <key> rebuild --bg --json --dev | Changes state | Runs the same ship path with a no-cache build. Use only when stale layers are supported by evidence. |
| Redeploy existing image | unaxis <project-slug> zone <key> deploy --bg --json --dev | Changes state | Pulls and recreates from an image that already exists. Do not run it automatically after a successful build. |
| Probe build reachability | unaxis <project-slug> build-doctor <key> --dev | Diagnostic | Checks Docker memory and probes build-time URLs from the build network. TIMEOUT or FAIL lines are the suspects. |
| Watch memory pressure | unaxis <project-slug> build-mem --dev | Diagnostic | Snapshots container memory and the buildx builder. Use during a build to distinguish capacity pressure from app failures. |
| Repair zone wiring | unaxis <project-slug> zone <key> doctor --dev | Changes config | Can patch legacy Compose, rewrite the proxy route, and register or update NPM. Use after the container is alive but wiring is stale. |
| Reconcile route cache | unaxis <project-slug> sync-routes --dev | Changes config | Rebuilds derived routes from live zones and environments. Do not edit proxy-config/routes.json manually. |
| Verify or repair NPM | unaxis <project-slug> audit-npm --dev | Changes config | Despite the name, it can create or update public proxy hosts. Use read-only npm search/logs first. |
| Restart the proxy | unaxis <project-slug> proxy restart --bg --json --dev | Changes state | Broad runtime action. Use only after evidence shows hot reload or route state did not apply. |
| Symptom | Evidence to collect | Next action |
|---|---|---|
| Queued build looks idle | Check stack JSON and bounded stack tails. A final 3:queued means the operation was accepted, not completed. | Wait for a terminal stack result. Do not start another build for the same zone. |
| Build stalls or ends with EOF | Use build-doctor for network reachability and build-mem for Docker memory pressure. | Free capacity through approved lifecycle actions or fix the failing fetch, then queue one rebuild. |
| Public host returns 502 | Check zone status, zone logs, proxy status, proxy logs, NPM search, and NPM logs with bounded reads. | Repair the layer that failed: zone runtime, proxy route cache, NPM host, or proxy runtime. |
| Public host serves the wrong app | Compare the public response, route cache, NPM forward target, zone container, and operation tail. | Use doctor or route reconciliation when wiring is stale. Do not rebuild blindly. |
| Old UI after a successful build | Use a cache-busting URL and inspect the pushed source tag, operation tail, zone runtime, and browser behavior. | Treat cache, wrong image, or wrong route as separate hypotheses before redeploying. |
Routes are derived state
proxy-config/routes.json is a cache rebuilt from zones, environments, and live containers. sync-routes, audit-npm, and zone <key> doctorcan write route, NPM, or Compose state; use read-only status and log checks first.
Operating contract
A visible, evidence-first workflow.
UNAXIS keeps long-running work and operational evidence in the same control plane used by the human operator.
- 01
Inspect first
Capture project, session, stack, zone, and environment state before changing anything.
- 02
Target explicitly
Choose the project slug and append --dev or --prod to project-scoped commands.
- 03
Verify the result
Check operation output, bounded logs, runtime status, and the public behavior you changed.
Documentation map
One operating model, seven guide areas.
Orientation, CLI, Zones, Environments, Databases, and Operations guidance are available here. Planned areas are named without linking to routes that do not exist yet.
- 01Available here
Getting Started / Orientation
Choose a project, target a running TUI, and establish the current state before acting.
Open orientation - 02Available here
CLI & Targeting
Learn project-scoped grammar, structured output, exit sentinels, and dev/prod targeting.
Open CLI guide - 03Available here
Zones
Inspect status and logs, use explicit dev lifecycle actions, and ship existing zones safely.
Open Zones guide - 04Available here
Environments
Understand execution boundaries, environment agents, containers, events, and security views.
Open Environments guide - 05Available here
Database Instances & Snapshots
Operate Core and runtime instances with clear backup, snapshot, clone, and restore safeguards.
Open Databases guide - 06Available here
Build, Routing & Troubleshooting
Follow background work, diagnose builds, inspect proxy state, and verify public behavior.
Open Operations guide - 07Planned
Architecture & Decisions
See how the TUI, CLI bridge, operation stack, environments, zones, and derived routes fit together.