Operations and output

Operation states, idempotency keys, waiting, exit codes, errors, labels and environment variables.

Operations

Every change is an operation recorded by the service before anything happens. Its status is one of:

Status	Meaning
`accepted`	Recorded; work has not started
`running`	In progress
`action_required`	Stopped safely; `nextStep` says what you need to do
`succeeded`	Finished, including cleanup
`failed`	Finished without success; `message` says why
`cancelled`	Cancelled, with cleanup finished

Operations have a message, often a nextStep, and for some commands a result.

Each command carries a key (--key in the CLI, key in MCP). Submitting the same key and command again returns the original operation instead of doing the work twice, which makes retries after a timeout or a dropped connection safe. The CLI generates a random key when you omit it. Reusing a key for a different command is rejected.

Waiting

Commands marked activity: "setting" in capabilities wait automatically in the CLI: pause/resume, repository enable-auto/disable-auto, environment register/configure/remove, instance stop/reconcile and operation cancel. They return the terminal operation, with exit code 1 for failure or cancellation and 3 for action required. If their --timeout expires, they report a wait_cancelled error and exit with 3; the operation may still be running. MCP command submission keeps its existing behavior.

--wait or vectis operation wait <id> waits until the operation leaves accepted and running, for up to --timeout milliseconds (default 120000). If time runs out, the CLI prints the operation as it is and exits with 3; the operation keeps going. MCP vectis_wait waits up to 120 seconds per call and returns timedOut: true in the same case. Stopping a wait never cancels the operation; use vectis operation cancel <id> for that.

Output and exit codes

The CLI always prints JSON: indented by default, compact with --json.

Exit code	Meaning
0	Success
1	The operation failed or was cancelled, or the command was rejected
3	The operation needs you (`action_required`) or is still running

Errors are printed as:

{
  "error": {
    "code": "machine_paused",
    "message": "The machine is paused.",
    "nextStep": "Run vectis resume."
  }
}

code is stable for scripts and agents; nextStep is written for people.

Runner labels

Every runner carries self-hosted, its OS label (Linux, macOS or Windows), ARM64 and vectis-<environment-id>. A job reaches it when its runs-on includes vectis-<environment-id> and only labels from that list. See Repositories and labels.

Environment variables

Variable	Effect
`VECTIS_HOME`	State directory, like `--home`
`VECTIS_APPLE_HELPER`, `VECTIS_KEYCHAIN_HELPER`	Native helpers; set automatically by the app and its command line tools
`VECTIS_QEMU`, `VECTIS_QEMU_IMG`, `VECTIS_SWTPM`	Windows runtime executables

Source checkouts also read CONVEX_URL and VECTIS_WEB_URL; see Build from source.