The Machine command line interface (CLI) controls Machine from a terminal. On your own computer the command is machine. This page shows the everyday dev loop, then lists every stable command and flag.

machine on your computer, kortix in a sandbox

The same CLI ships two ways. You install it on your computer as machine. Every session sandbox already has it on PATH as kortix, signed in for you, and agents call it by that name. The commands and flags are identical. This page writes machine; inside a sandbox, type kortix instead.

Names the CLI reads and writes keep their original spelling under both commands: kortix.yaml, .kortix/link.json, ~/.config/kortix/config.json, and KORTIX_* environment variables.

Install

On macOS or Linux:

bash

curl -fsSL https://themachine.myapps.ai/install | bash

On Windows, in PowerShell:

powershell

irm https://themachine.myapps.ai/install.ps1 | iex

The installer downloads the build for your OS and CPU, checks its SHA-256 checksum against the release manifest, and puts machine on your PATH. Builds exist for macOS and Linux on x64 and arm64, and for Windows on x64. Windows on Arm runs the x64 build.

OS	Installs to	Put on `PATH` by
macOS, Linux	`~/.machine/machine`	A link in `/usr/local/bin` when that folder is writable, otherwise in `~/.local/bin`. The installer adds `~/.local/bin` to your shell profile when it is missing.
Windows	`%LOCALAPPDATA%\Machine\bin\machine.exe`	Your user `PATH`. Open a new terminal to pick it up.

Installer settings:

Variable	Effect
`MACHINE_HOME`	macOS and Linux only. Install directory. Default: `~/.machine`.
`MACHINE_NO_MODIFY_PATH`	Set it to leave `PATH`, `/usr/local/bin`, and your shell profile alone. Run the binary by its full path.
`MACHINE_INSTALL_BASE`	Download from another Machine deployment. Default: `https://themachine.myapps.ai`.

To set one, put it in front of bash: curl -fsSL https://themachine.myapps.ai/install | MACHINE_NO_MODIFY_PATH=1 bash.

Command	Effect
`machine update`	Re-run the install script for your OS and replace the binary with the latest release.
`machine uninstall [-y\|--yes] [--keep-auth] [--keep-home]`	Remove `~/.machine`, the `machine` link in `/usr/local/bin` or `~/.local/bin`, `~/.kortix`, and the stored sign-in. `--keep-auth` keeps the sign-in. `--keep-home` keeps `~/.kortix`.
`machine version`	Print the CLI version.

machine uninstall only looks for the default ~/.machine folder. If you installed with a custom MACHINE_HOME, delete that folder yourself.

On Windows, machine uninstall removes the stored sign-in but not the program itself. Delete the %LOCALAPPDATA%\Machine\bin folder and remove it from your user PATH to finish.

Auth model

The CLI stores authentication per host, not globally. A host is one Machine API endpoint. Four hosts exist by default: cloud (Machine, at https://machineapi.myapps.ai), selfhost (your self-hosted stack), local-dev, and kortix-internal-dev. You can add more.

The config file lives at ~/.config/kortix/config.json, mode 0600. Override its path with KORTIX_CONFIG_FILE.

The CLI follows one hierarchy: host → account → project → session. You sign in to a host, pick an account inside it, pick a project inside that account, and open sessions inside the project. machine hosts login walks the first three steps in order: it signs you in, picks the account, then sets a default project.

machine login opens the Machine website in your browser. One click authorizes the CLI, and the website hands the CLI a personal access token. You can also sign in with an API key you created yourself: machine login --token mach_pat_.... The CLI accepts keys that start with mach_pat_ or kortix_pat_. A user token sees every account and project you belong to. A project token is auto-minted for a session sandbox and scoped to one project. See Token scope.

The dev loop

This loop assumes the CLI is installed and you ran machine login. See Quickstart for setup.

Link a repo

Start a new project, or link an existing repo folder to one.

To scaffold a new project:

bash

machine init my-app
cd my-app

machine init creates a project directory with the general-purpose starter. Its kortix.yaml declares kortix_version: 2 and runs OpenCode.

To link an existing cloned repo to a project you already created:

bash

machine projects link <project-id>

This command writes .kortix/link.json in the current directory. The CLI reads this file to find your project on every command run from this folder. If you plan to run machine ship first, skip this step. It links a new project for you when none exists.

Ship your code

bash

machine ship

machine ship lints your kortix.yaml, commits local changes, pushes your branch, and prompts for any missing secret or connection. Run it each time you want your local changes on the cloud project. The first run also creates the cloud project and repo if you have not linked one yet.

Run and attach to sessions

Start a session with a prompt:

bash

machine sessions new --prompt "Build the login page" --wait

Each session runs in its own sandbox, on its own branch. --wait blocks until the session is ready.

Attach to a session from your terminal:

bash

machine connect

With no session id, machine connect (alias: attach) opens a session picker for the bound project — running sessions attach immediately, stopped ones boot first, and + New session starts a fresh sandbox — then lands you in the full OpenCode TUI attached to that session. Pass an id to skip the picker: machine connect <session-id>.

The CLI manages the opencode binary for you: on first connect it downloads the exact version the session's server runs and caches it under ~/.kortix/opencode/<version>/, so the TUI and server never skew. Set KORTIX_OPENCODE_BIN to force your own binary.

For a lighter-weight line-based chat instead of the full TUI, run:

bash

machine sessions chat

This opens an interactive chat with your most recent session. Add an id to target a specific session: machine sessions chat <id>.

To open a raw shell in the sandbox, with no agent involved, run:

bash

machine sessions shell

List your running sessions at any time:

bash

machine sessions ls

Review with change requests

An agent opens a change request (CR) when its session has commits ready to merge. List, inspect, and merge them from the CLI.

bash

machine cr ls
machine cr diff 1
machine cr merge 1

machine cr ls lists change requests for the linked project. machine cr diff <cr> shows the unified patch. machine cr merge <cr> merges it into the project's default branch. Accept a CR number or its full id.

Reference

Auth commands

Command	Effect
`machine login [--host <name>] [--api <url>] [--token <pat>] [--account <slug>] [--no-project]`	Sign in to the active host, or the named one. Opens a browser by default; `--token` signs in headless with a `mach_pat_` or `kortix_pat_` key. `--no-project` skips the default-project pick.
`machine logout [--host <name>]`	Remove the token for the active host, or the named one.
`machine whoami [--host <name>] [--json] [--token-only]`	Print the signed-in user and active account.
`machine token [--host <name>]`	Shortcut for `machine whoami --token-only`.

machine hosts login / hosts logout / hosts whoami are the canonical forms. login / logout / whoami are shortcuts that act on the active host.

Hosts

Command	Effect
`machine hosts ls [--json]`	List every host and its auth status.
`machine hosts login [<name>] [--token <pat>] [--api <url>] [--account <slug>] [--no-project]`	Sign in to a host. An unknown name registers the host first.
`machine hosts logout [<name>]`	Remove the token for a host.
`machine hosts use <name>`	Switch the active host.
`machine hosts add <name> --url <url> [--dashboard-url <url>] [--login]`	Register a new host. `--login` signs in right after.
`machine hosts rm <name> [--force]`	Remove a host.
`machine hosts info [<name>] [--json]`	Show details for one host.
`machine hosts current [--json]`	Print the active host name.

A remote host URL that starts with http:// is normalized to https://. The CLI never sends a token over plain HTTP to a remote host. localhost is exempt.

Accounts

Command	Effect
`machine accounts ls [--json]`	List the accounts you belong to on the active host.
`machine accounts use [<slug-or-id>]`	Switch the active account.
`machine accounts current [--json]`	Print the active account.
`machine accounts info [<slug-or-id>] [--json]`	Show one account.

Projects

A command resolves "the project" in this order:

The --project flag.
The KORTIX_PROJECT_ID environment variable.
.kortix/link.json in the exact working directory.
The global default set by machine projects use.

Command	Effect
`machine projects ls [--all] [--json]`	List projects on the active account. `--all` spans every account you belong to.
`machine projects info [<id>] [--json]`	Show one project. Default: the linked or default project.
`machine projects use [<id>]`	Set the global default project. Switches the active account if the project lives elsewhere.
`machine projects unset`	Clear the global default project.
`machine projects link [<id>]`	Bind the current directory to a project. Writes `.kortix/link.json`.
`machine projects unlink`	Remove `.kortix/link.json`.
`machine projects open [<id>]`	Open a project's dashboard page in your browser.
`machine projects clone [<id>] [dir]`	Clone a project's repo through the authenticated Machine git proxy.
`machine projects rm [<id>] [--purge] [-y\|--yes]`	Archive a project. `--purge` also deletes its managed git repo.

Project scaffold

machine init [project-name] [options] creates a new project directory. The starter writes a v2 kortix.yaml and the canonical .kortix/opencode system-skill source. The command can wire local coding-tool discovery without changing the cloud OpenCode runtime. The command does not write .kortix/link.json. machine ship or machine projects link create that file.

Flag	Meaning
`--name <project>`	Project name.
`--primary <agent>`	Primary agent.
`--agents <csv>`	Local coding-agent integrations to wire up.
`--force`	Configure the current directory in place instead of scaffolding a new one.
`--overwrite`	Overwrite existing files.
`--no-git`	Skip git init.
`-y, --yes`	Don't prompt.

The local coding-tool selection does not change the cloud OpenCode runtime.

machine init does not include a marketplace picker. Adding a marketplace skill is an agent import: run machine marketplace install <id-or-name>, or start a session and ask the agent to bring one in.

Ship

machine ship stages, commits, and pushes your current branch to the project's git repo. Run it once to create the project. Run it again any time to sync. Alias: machine deploy.

Each run:

Parses and validates kortix.yaml (skip with --no-verify).
Commits any dirty working tree (skip with --no-commit).
Prompts for any missing env secret (skip with --no-env).
Pushes the current branch to the same-named remote branch.
Connects any declared connector that still needs auth (skip with --no-connect).

An existing GitHub origin links through the Machine GitHub App. Any other existing origin is registered as-is. No origin creates a managed Machine git repo.

Option	Effect
`--name <project>`	Display name for a new project.
`--account <id\|slug>`	Account to create the project under (first ship only).
`--origin <managed\|git-url>`	Override the inferred origin choice.
`--github-token <pat>`	Link a GitHub origin with this token instead of the GitHub App.
`-m, --message <text>`	Commit message.
`--no-commit` / `--no-verify` / `--no-env` / `--no-connect`	Skip that step.
`-y, --yes`	Don't prompt.
`-n, --dry-run`	Print what would happen; change nothing.
`--project <id>` / `--host <name>`	Target a non-default project or host.

Sessions

Each session runs in one sandbox on its own branch.

Command	Effect
`machine sessions ls`	List every session on the project.
`machine sessions status [--all] [--json]`	Every session and what its agent is doing right now. Aliases: `overview`, `ps`.
`machine sessions info <id> [--json]`	Detail view: status, branch, agent, sandbox URL.
`machine sessions new [--prompt "<text>"] [--agent <name>] [--model <id>] [--wait] [--connect] [--json]`	Start a session. `--connect` attaches the OpenCode TUI once it is ready (implies `--wait`); on an interactive terminal without it, the CLI asks whether to connect after creation. `--model <id>` overrides the project's default model. `--wait` blocks until it is running (up to ~5 minutes). Use `--secret <id>` or `--no-secrets` to narrow Secret access. These Secret flags require a backend token. Use `--connector <alias>=<authorization-id>` or `--no-connectors` to set Connector access. Use `--require-connector <alias>` to require an authorization before provisioning. Scope flags are repeatable. Use `--context <key>=<value>` for non-secret runtime context.
`machine sessions chat [<id>] [--prompt "<text>"] [--new] [--agent <name>] [--json]`	Talk to a session's agent. Interactive by default. Alias: `talk`. Top-level `machine chat` also works.
`machine sessions connect [<id>] [-- <opencode args>]`	Attach the OpenCode TUI to the session's OpenCode server. Also available top-level: `machine connect` / `machine attach`. With no id, opens a session picker (running, stopped-with-restart, or new). The CLI auto-downloads the version-matched `opencode` binary (cache: `~/.kortix/opencode/<version>/`; override: `KORTIX_OPENCODE_BIN`).
`machine sessions shell [<id>] [--new]`	Open a raw interactive terminal in the sandbox, with no agent. Aliases: `terminal`, `ssh`.
`machine sessions log [<id>] [--limit <n>] [--json]`	Print recent messages, read-only. Aliases: `messages`, `history`.
`machine sessions pending <id> [--json]`	List open tool-permission or question prompts. Alias: `prompts`.
`machine sessions approve <id> [<req-id>] [--always] [--reject] [--message "<text>"]`	Answer a permission prompt.
`machine sessions answer <id> [<req-id>] [--option <v>]... [--text "<text>"] [--reject]`	Answer a question prompt.
`machine sessions digest [--since <7d>] [--json]`	Compact multi-session review. Aliases: `review`, `summary`.
`machine sessions scope <id> [scope options] [--json]`	Read or replace Secret and Connector access. Alias: `access`. Use `--secret <id>`, `--no-secrets`, or `--inherit-secrets` for Secrets. Use `--connector <alias>=<authorization-id>` or `--no-connectors` for Connector bindings. Use `--require-connector <alias>` or `--no-required-connectors` for required Connectors. Provided categories replace their current values. Omitted categories remain unchanged. Changes apply to the next prompt. Removed Secret values remain in existing context if the session already read them.
`machine sessions preview <id> [port] [--port <n>] [--json]`	Print a clickable preview URL for a sandbox port. Default port: `3000`.
`machine sessions restart <id>`	Restart the session's sandbox.
`machine sessions rename <id> <name>`	Set a session's name. Pass `""` to clear it.
`machine sessions rm <id>`	Stop and delete a session.
`machine sessions open <id>`	Open a session's dashboard page in your browser.

Inside a sandbox, KORTIX_SESSION_ID is your own session's id.

Change requests

A change request (CR) merges one branch into another on any git host. It is the only way for an agent to land session work on the default branch. See Change requests.

Command	Effect
`machine cr ls [--status open\|merged\|closed\|all] [--project <id>]`	List CRs. Default: `--status open`.
`machine cr show <cr> [--project <id>]`	Show one CR, including its merge preview. Alias: `info`.
`machine cr diff <cr> [--no-color] [--json]`	Print a CR's unified diff.
`machine cr open --title "<text>" [--description "<text>"] [--head <ref>] [--session <id>] [--base <ref>]`	Open a CR. Aliases: `new`, `create`. Inside a sandbox, `--head` and `--session` default automatically. `--base` defaults to the project's default branch.
`machine cr merge <cr> [--message "<text>"]`	Merge an open CR. Fast-forward when possible, three-way merge otherwise.
`machine cr close <cr>`	Close an open CR without merging.
`machine cr reopen <cr>`	Reopen a closed CR. Merged CRs are terminal.

<cr> accepts a per-project number (3) or the full id. Inside a sandbox, kortix cr reads its token automatically — no login or link needed.

Secrets

Encrypted values stored on the project. Only a secret with Sandbox delivery (the default) is injected as a plain environment variable into session sandboxes. Machine service and Network boundary secrets never enter the sandbox. Change the mode with machine secrets delivery. See Secrets.

Command	Effect
`machine secrets ls`	List secrets by identifier and manifest `env` spec. Marks required-but-missing values.
`machine secrets set NAME=VALUE ... [--identifier <id>]`	Upsert one or more secrets. `NAME=-` reads the value from stdin.
`machine secrets request NAME ... [--scope runtime\|connector] [--expires <min>]`	Mint a link for a human to enter a value directly — you never see the raw value.
`machine secrets unset NAME ...`	Remove secrets.
`machine secrets delivery IDENTIFIER runtime\|broker\|egress\|denied [policy options]`	Set the delivery mode: `runtime` is Sandbox, `broker` is Machine service, `egress` is Network boundary, `denied` is Disabled.
`machine secrets call IDENTIFIER URL`	Send one policy-bound HTTPS request through the broker.
`machine secrets sync`	Re-push project secrets to running sandboxes.

Env

Command	Effect
`machine env pull [--out <path>] [--force]`	Write a `.env` skeleton — names only. Values never leave the cloud.
`machine env push --from <path>`	Upload every `NAME=VALUE` from a dotenv file as a secret.

Agents

Per-agent model settings on the linked project.

Command	Effect
`machine agents models [--json]`	Show every agent's pinned model and the fallback default.
`machine agents model <agent> <model-id>`	Pin an agent to a plain model id, for example `machine agents model kortix glm-5.2`. Applies to new sessions.
`machine agents model <agent> --clear`	Clear the pin — the agent follows the default again.

Channels

Manages the project's connection to a chat platform. Tokens are stored encrypted in the project's secrets and resolved server-side — they are never injected into the sandbox.

Command	Effect
`machine channels status [--json]`	Show the current connection.
`machine channels connect [--wait] [--timeout <sec>]`	Connect in one step: prints an install link. `--wait` polls until the install lands.
`machine channels connect --manual [--bot-token <token>] [--signing-secret <secret>]`	Bring-your-own-app mode: save a bot token and signing secret directly.
`machine channels disconnect`	Remove the project's channel secrets.
`machine channels manifest`	Print the app manifest JSON for the bring-your-own-app path.

--platform slack|teams selects the platform; default slack. See Connectors.

Connectors

Connectors an agent calls as tools. add, rm, and policy set edit the local kortix.yaml; run machine ship to apply. add and rm also take --apply, which skips the local file and changes the cloud project immediately (Machine commits the edit to kortix.yaml on the default branch and syncs).

Command	Effect
`machine connectors ls [--json]`	List connectors and their status.
`machine connectors show <slug> [--json]`	Show one connector's tools.
`machine connectors add <slug> --provider <p> [options] [--apply]`	Add a connector.
`machine connectors rm <slug> [--apply]`	Remove a connector.
`machine connectors rename <slug> <name>`	Set a connector's display name.
`machine connectors sync`	Reconcile the catalog from the shipped `kortix.yaml`.
`machine connectors credential <slug> [value]`	Set a connector's credential.
`machine connectors secret <slug> <identifier> [--clear]`	Use a project secret as the connector's server-side credential. `--clear` removes the binding.
`machine connectors connect <slug> [--expires <min>]`	Mint a shareable one-click connect link for a human. The connection finalizes on its own once they finish.
`machine connectors apps [<query>] [--json]`	Browse the connector app catalog.
`machine connectors policy ls [--json]`	Show project-wide execution policy.
`machine connectors policy set --default <risk\|allow_all>`	Set the default execution mode.
`machine connectors policy <slug> ls\|set <match> <allow\|ask\|block>\|rm <match>\|clear`	Manage one connector's tool-call rules.

Sandboxes

Manages the project's sandbox images. A template defines an image or Dockerfile plus resources; a build produces the snapshot sessions boot from.

Command	Effect
`machine sandboxes ls [--json]`	List templates and live provider state.
`machine sandboxes builds [--json]`	Recent build log.
`machine sandboxes health [--json]`	Primary template readiness.
`machine sandboxes add <slug> (--image <i>\|--dockerfile <p>) [options]`	Create a custom template and start a build.
`machine sandboxes update <slug> [options]`	Update a template.
`machine sandboxes build <slug>`	Trigger a rebuild.
`machine sandboxes rebuild <slug>`	Force-rebuild: delete the existing snapshot first.
`machine sandboxes rm <slug>`	Delete a template.
`machine sandboxes fix`	Start a session seeded with the last failed build log, to repair it.

add/update options: --name <label>, --cpu <n>, --memory <n> (GiB), --disk <n> (GiB).

Marketplace

Browse marketplace items and install one. Installing is an agent import: install starts a session on the project, and its agent clones the item, merges what fits, and opens a change request for you to review.

Command	Effect
`machine marketplace search [query]`	Search marketplace items.
`machine marketplace list`	List marketplace items.
`machine marketplace show <id-or-name>`	Show one marketplace item.
`machine marketplace install <id-or-name> [--project <id>]`	Start a session that imports the item into the linked project, or the one `--project` names.

Options: --query <text>, --type <type>, --source <source>, --host <name>, --json.

System skills

The Machine system skills are the platform's own documentation. They cover sessions, sandboxes, OpenCode, the connector, memory, and channels. The API serves them live, so they match the deployed host version. The binary and a token are enough for an agent to retrieve this context.

Command	Effect
`machine system-skills list`	List the Machine system skills. Default subcommand.
`machine system-skills get <name> [--full]`	Print one skill's current `SKILL.md`. `--full` adds its referenced files.
`machine system-skills path [name]`	Print a skill's on-disk directory in this project.

Options: --host <name>, --json.

machine skills is a permanent alias for the same command.

This list is always the system skills, never a mix. Optional skills live in the marketplace: machine marketplace list --type skill.

Connector

The in-sandbox agent's interface to every connector. Agents run these as kortix connectors … inside the sandbox. Every call is checked, resolved, and audited server-side; the CLI never holds a third-party credential. Auth: KORTIX_CLI_TOKEN. Output is JSON.

Command	Effect
`kortix connectors discover "<intent>"`	Search tools by natural-language intent.
`kortix connectors show <connector>.<action>`	Show an action's input schema.
`kortix connectors call <connector>.<action> '<json-args>'`	Run a tool. A governed call returns its authenticated `approval_url` immediately. The server resumes the session after one approve or deny decision.
`kortix connectors add <slug> --provider pipedream --app <app> --apply`	Add a connector to the project immediately, then connect it. Without `--apply`, it only edits the sandbox's copy of `kortix.yaml`, which takes effect once that change is merged.
`kortix connectors rm <slug> --apply`	Remove a connector from the project immediately. Without `--apply`, it only edits the sandbox's copy of `kortix.yaml`.
`kortix connectors connect <slug> [--expires <min>]`	Mint a connect link for a human.
`kortix connectors mcp`	Run the optional stdio MCP compatibility server.

Files

Read-only view of the project's git repo. Operates on the default branch unless --ref names another branch, tag, or commit.

Command	Effect
`machine files ls [<path>]`	List files under a path.
`machine files cat <path>`	Print a file's contents.
`machine files search <query> [--content]`	Search filenames, or file contents with `--content`.
`machine files history <path>`	Commit history for one file.
`machine files branches`	List branches.
`machine files commits [--path <p>]`	List commits on `--ref`.
`machine files show <sha>`	Show one commit and its changed files.
`machine files diff <sha> [--path <p>]`	Print a commit's unified patch.

Options on every subcommand: --ref <ref>, --path <p>, --limit <n>, --json.

Triggers

A trigger starts a session from a schedule, a webhook, or a monitor (experimental). add, rm, enable, disable edit the local manifest — run machine ship to apply. pause/resume flip a separate, server-side switch. See Triggers.

Command	Effect
`machine triggers ls [--json]`	List triggers and their runtime state.
`machine triggers add <slug> [options]`	Append a trigger to the manifest.
`machine triggers rm <slug>`	Remove a trigger.
`machine triggers info <slug> [--json]`	Show one trigger.
`machine triggers fire <slug>`	Fire a trigger manually.
`machine triggers enable <slug>` / `disable <slug>`	Turn one trigger on or off.
`machine triggers pause` / `resume`	Deactivate or reactivate every trigger on the project, server-side.

add options: --type <cron\|webhook\|monitor> (default cron), --prompt <text> (required), --agent <name>, --cron <expr>, --timezone <tz> (default UTC), --secret-env <NAME>, --name <label>, --disabled.

Monitor options (--type monitor, experimental): --run <cmd> (required, a repo-relative command the platform keeps running; each line it prints fires the trigger), --mode <poll\|stream> (required), --interval <dur> (poll mode only, minimum 30s, for example 5m), --expect-event-within <dur> (minimum 5m; if no event arrives in that window, the trigger fires a lifecycle event instead).

Access

Who can use the linked project. Roles: manager, editor, member.

Command	Effect
`machine access ls [--json]`	List members and their project roles.
`machine access invite <email> --role <r>`	Invite someone to the project.
`machine access grant <user-id> --role <r>`	Set a member's project role.
`machine access revoke <user-id>`	Remove a member's project access.
`machine access pending [--json]`	List pending invitations.
`machine access cancel <invite-id>`	Cancel a pending invitation.

Audit

The audit commands read the centralized reconstruction log. Account and project lists are newest first. A session timeline is ordered by its monotonic session_sequence. --all follows every continuation cursor.

Command	Effect
`machine audit ls [filters] [--all] [--json]`	List account events.
`machine audit project <project-id> [filters] [--all] [--json]`	List one project's events.
`machine audit session <session-id> --project <project-id> [--all] [--json]`	Reconstruct one session in order.
`machine audit export [filters] --format csv\|jsonl --out <file>`	Resume every export page into one file.

Filters: --actor, --actor-type, --project, --session, --source, --phase, --outcome, --action, --resource-type, --request-id, --correlation-id, --query, --since, --until, --cursor, and --limit. Account lists and exports require audit.read and the account's auditAccess entitlement. Project-wide lists require project.members.manage because they can include private-session metadata. Session reconstruction requires project.session.read and visibility of that session.

Roles

Account-level custom IAM roles and policy bindings. Built-in roles are read-only references; custom roles are yours to create, edit, and bind.

Command	Effect
`machine roles ls [--json]`	List roles, built-in and custom.
`machine roles show <role> [--json]`	Show one role's permissions and usage.
`machine roles actions [--json]`	List the permission catalog.
`machine roles create <key> --name <n> [options]`	Create a custom role.
`machine roles set-actions <role> --actions a,b`	Replace a custom role's permissions.
`machine roles rm <role>`	Delete a custom role.
`machine roles assignments [--project <id>] [--json]`	List policy bindings.
`machine roles assign <role> --to <type>:<id>`	Bind a role to a member, group, or token.
`machine roles unassign <policy-id>`	Remove a binding.
`machine roles export [--project <id>] [--out <file>] [--format toml\|json]`	Dump roles and bindings to a file.
`machine roles import <file>`	Apply a roles and bindings file.

Grants

Assigns project resources to people. Assigning an agent to a member or group gives them the secrets and connectors that agent declares in kortix.yaml.

Agents themselves need no grant for connectors or Sandbox secrets: every agent in the project reaches every connected connector and every Sandbox secret. An agent's own declaration controls its kortix_cli actions and which Network boundary and Machine service secrets it receives. See Secrets and Agents.

Command	Effect
`machine grants ls [--json]`	List grants, and which agents can be granted.
`machine grants assign <agent-name> --to <who> [--group]`	Assign an agent to a member, or a group with `--group`.
`machine grants revoke <grant-id>`	Remove a grant.

Manifest validation

Command	Effect
`machine validate [--file <path>] [--json] [--scopes]`	Validate the manifest against the canonical schema. Resolves `kortix.yaml` first, then `kortix.toml`. Exit codes: `0` valid, `1` errors, `2` file missing.
`machine schema [--version 1\|2] [--url]`	Print the manifest's JSON Schema. `--url` prints the schema URL instead.

See Manifest reference.

Self-host

machine self-host <subcommand> runs your own Machine stack with Docker Compose on a server you control. Subcommands: init, start, update, version, stop, restart, status, ps, doctor, logs, open, configure, uninstall, and env ls/env set/env rotate. Run machine self-host --help for the full list.

Common flags: --instance <name> (default default), --domain <domain>, --tunnel cloudflare, --version/--tag/--release <v>, --channel stable|latest (default stable), --auto-update on|off (default on; forced off by --local-images), --update-time <HH:MM> / --update-tz <tz> (auto-updater schedule), --local-images (run locally-built images; dev mode), --enterprise-license (unlock SSO/SCIM/RBAC/audit), --admin-email <email>, --no-restrict-account-creation (let any signed-in user create new accounts/orgs; default is admin-only), --restrict-account-creation (re-enable the admin-only default), --json, --yes.

Token scope

A user token is scoped to every project on your accounts. API keys you create on the website start with mach_pat_. The token machine login saves for you, and every token minted before mach_pat_ existed, start with kortix_pat_. Both work everywhere. A project token is scoped to one project and auto-injected into that project's sandboxes. See the full token-family reference at Session runtime.

Exit codes

Code	Meaning
`0`	Success.
`1`	Operation failed. Diagnostics print to stderr.
`2`	Bad flag, unknown subcommand, or missing required argument.

CLI

Install

Auth model

The dev loop

Link a repo

Ship your code

Run and attach to sessions

Review with change requests

Reference

Auth commands

Hosts

Accounts

Projects

Project scaffold

Ship

Sessions

Change requests

Secrets

Env

Agents

Channels

Connectors

Sandboxes

Marketplace

System skills

Connector

Files

Triggers

Access

Audit

Roles

Grants

Manifest validation

Self-host

Token scope

Exit codes

On this page