CLI reference

Generated from the command definitions of this release. capyctl <command> --help prints the same descriptions.

`capyctl`

Run vLLM, SGLang, TensorFold and llama.cpp models on your own GPUs

Usage: capyctl [OPTIONS] <COMMAND>

Subcommands:

start — Start the server, a host, standalone, or a deployment
init — Write a starter configuration file for a server or a host
invite — Create a single-use invitation file that lets a GPU machine join the server. With --recover, let a revoked host rejoin as itself
join — Join this machine to a server with an invitation file. With --recover, rejoin a revoked host as itself; its state is kept
list — List hosts, deployments or engines as a table
inspect — Print the full JSON record of a host or a deployment
doctor — Check a host. Not available in this release
deploy — Create a deployment from a YAML file, or update one
status — Show a deployment’s state and its instances
park — Park a deployment: free its GPU memory and keep it ready to wake. The next request for it wakes it
stop — Stop a deployment’s engines, or one instance. The deployment is kept
preinitialize — Start a deployment, check it answers, then park it, so its first request only has to wake it
delete — Delete a deployment and its routes once its engines are confirmed stopped. Model files and caches on hosts are never touched
validate — Check a configuration file without starting anything
config — Show the settings a role would run with and where each came from
drain — Stop every engine on a host and keep its deployments; they start again when a request needs them. Stopping the capyctl service does not do this
revoke — Disconnect a host for good. Its capyctl process exits with code 14; its engines keep running but get no more requests, and their GPU memory stays counted as used. Bring it back with invite host --recover and join host --recover
prune — Remove downloaded model copies that no deployment uses from this machine’s model store. Deleting a deployment never does this
engine — Register, list or remove the vLLM, SGLang, TensorFold and llama.cpp installations on this machine. Each one becomes a runtime profile deployments can name
version — Print this build’s version and, for a release build, the commit it was built from. --version prints the version line only

Options:

--config <FILE> — The role document (server, host or standalone). Wins over CAPYCTL_CONFIG; without either, a command uses the role running on this machine
--output <TARGET> — Where init and invite write their file. --output json also prints JSON results, as --format json does
--format <FORMAT> — How results print: text (the default: tables and summaries) or json. A role (start server|host|standalone) prints JSON lines when its output is not a terminal, unless this option says otherwise

Possible values: text, json
--json — Short for --format json
--request-id <ID> — A ULID that names this change. Running the command again with the same id continues the same change instead of starting a new one
--state-dir <DIR> — The state root: where implicit role documents, standalone state and client credentials live. Wins over CAPYCTL_STATE_DIR (default $XDG_STATE_HOME/capyctl, else ~/.local/state/capyctl)

`capyctl start`

Start the server, a host, standalone, or a deployment

Usage: capyctl start <COMMAND>

Subcommands:

server — Start the server
host — Start a host on this GPU machine
standalone — Start the server and one host together on this machine
deployment — Start a deployment’s engines
instance — Start one instance, <deployment>/<index>

`capyctl start server`

Start the server

Usage: capyctl start server [OPTIONS]

Options:

--listen <ADDR:PORT> — Serve inference on this address for this run instead of the document’s listeners.inference.bind (default 0.0.0.0:8443), for example 127.0.0.1:8443 or a Tailscale address. Wins over CAPYCTL_INFERENCE_ADDR
--no-inference-auth — Serve inference without the API key for this run. Every client that can reach the address can use the models; a non-loopback address prints a warning. Wins over CAPYCTL_INFERENCE_AUTH and listeners.inference.authentication
--management-listen <ADDR:PORT> — Serve the management API on this loopback address for this run (default 127.0.0.1:7443). Wins over CAPYCTL_MANAGEMENT_ADDR and listeners.management.bind
--group-stall-timeout <DURATION> — How long a request to a multi-node group may wait for its first token before the server probes the group’s head once (default 120s, 1s to 3600s). Wins over CAPYCTL_GROUP_STALL_TIMEOUT and groups.stall_timeout
--set <PATH=VALUE> — Set any setting of the role document for this run, by its YAML path (repeatable), e.g. –set shutdown.drain_timeout=45s. Wins over CAPYCTL_SET__ and the document; a setting that also has a named flag or variable must agree with it. Secrets cannot be set here

`capyctl start host`

Start a host on this GPU machine

Usage: capyctl start host [OPTIONS]

Options:

--debug-engine-logs — Retain full native engine logs in private files (may contain secrets)
--models-root <DIR> — The models directory a relative model path resolves under for this run (default ~/models). Wins over CAPYCTL_MODELS_ROOT and model_store.path
--model-sources <allowed|disabled> — Allow or disable Hugging Face and HTTP model downloads for this run (default allowed). Wins over CAPYCTL_MODEL_SOURCES and model_sources in the document
--model-sources-max <SIZE> — The most bytes downloaded models may take (default 500GiB). Wins over CAPYCTL_MODEL_SOURCES_MAX and model_sources.max_bytes
--model-sources-path <DIR> — The directory downloads are kept under (default: the models directory). Wins over CAPYCTL_MODEL_SOURCES_PATH and model_sources.path
--hf-endpoint <URL> — The Hugging Face endpoint downloads use (https://, default https://huggingface.co). Wins over CAPYCTL_HF_ENDPOINT, HF_ENDPOINT and model_sources.huggingface_endpoint
--model-sources-plain-http <allowed|disabled> — Allow plain http:// URLs for HTTP model downloads on this run (default disabled; the download is still checked against its sha256). Wins over CAPYCTL_MODEL_SOURCES_PLAIN_HTTP and model_sources.plain_http
--trust-declared-digest <true|false> — Trust a local checkpoint’s declared canonical content_fingerprint without hashing it in full, true or false (default). Wins over CAPYCTL_TRUST_DECLARED_DIGEST and checkpoints.trust_declared_digest
--vllm-bin <PATH> — The vLLM executable this role runs as its local profile. Wins over CAPYCTL_VLLM_BIN and local_engine.vllm
--sglang-bin <PATH> — The SGLang interpreter this role runs as its local profile. Wins over CAPYCTL_SGLANG_BIN and local_engine.sglang
--tensorfold-bin <PATH> — The TensorFold executable (<venv>/bin/tensorfold) this role runs as its local profile. Wins over CAPYCTL_TENSORFOLD_BIN and local_engine.tensorfold
--llamacpp-bin <PATH> — The llama.cpp llama-server binary this role runs as its local profile. Wins over CAPYCTL_LLAMACPP_BIN and local_engine.llamacpp
--engine-fingerprint <TEXT> — The build fingerprint the local engine publishes (default: what <engine> --version prints). Wins over CAPYCTL_ENGINE_FINGERPRINT and local_engine.build_fingerprint
--engine-args <ARGS> — Host-fixed vLLM arguments of the local engine, one string. Wins over CAPYCTL_ENGINE_ARGS and local_engine.args
--deep-park <on|off> — Deep parking of the local engine, on (default) or off. Wins over CAPYCTL_DEEP_PARK and local_engine.deep_park
--trust-remote-code <true|false> — Whether the local engine may run checkpoint-supplied Python, true or false (default). Wins over CAPYCTL_TRUST_REMOTE_CODE and local_engine.trust_remote_code
--installation-drift <warn|refuse> — What a launch does when the local engine’s files changed, warn (default) or refuse. Wins over CAPYCTL_INSTALLATION_DRIFT and local_engine.installation_drift
--runtime-dir <DIR> — capyctl’s runtime directory (default: the managed copy in the state directory). Wins over CAPYCTL_RUNTIME_DIR and runtime_dir
--engine-ports <START-END> — The engines’ loopback port range, start-end (default 8100-8199). Wins over CAPYCTL_ENGINE_PORTS and resource_policy.endpoint_port_range
--cuda-home <DIR> — The CUDA toolkit directory of the local engine (its bin/ joins the engine PATH for JIT builds; default none). Wins over CAPYCTL_CUDA_HOME and local_engine.cuda_home
--peer-address <IP> — The address this host’s group peers reach it on, an IP address such as 192.0.2.10 (default none). Wins over CAPYCTL_PEER_ADDRESS and resource_policy.groups.peer_address
--rendezvous-ports <START-END> — The group rendezvous port range, start-end (default 25000-25099). Wins over CAPYCTL_RENDEZVOUS_PORTS and resource_policy.groups.rendezvous_port_range
--require-rdma <true|false> — Refuse group work on this host when RDMA tuning (memlock, infiniband) is missing (default false). Wins over CAPYCTL_REQUIRE_RDMA and resource_policy.groups.require_rdma
--set <PATH=VALUE> — Set any setting of the role document for this run, by its YAML path (repeatable), e.g. –set shutdown.drain_timeout=45s. Wins over CAPYCTL_SET__ and the document; a setting that also has a named flag or variable must agree with it. Secrets cannot be set here

`capyctl start standalone`

Start the server and one host together on this machine

Usage: capyctl start standalone [OPTIONS]

Options:

--debug-engine-logs — Retain full native engine logs in private files (may contain secrets)
--listen <ADDR:PORT> — Serve inference on this address for this run instead of the document’s listeners.inference.bind (default 0.0.0.0:8443), for example 127.0.0.1:8443 or a Tailscale address. Wins over CAPYCTL_INFERENCE_ADDR
--no-inference-auth — Serve inference without the API key for this run. Every client that can reach the address can use the models; a non-loopback address prints a warning. Wins over CAPYCTL_INFERENCE_AUTH and listeners.inference.authentication
--models-root <DIR> — The models directory a relative model path resolves under for this run (default ~/models). Wins over CAPYCTL_MODELS_ROOT and model_store.path
--model-sources <allowed|disabled> — Allow or disable Hugging Face and HTTP model downloads for this run (default allowed). Wins over CAPYCTL_MODEL_SOURCES and model_sources in the document
--model-sources-max <SIZE> — The most bytes downloaded models may take (default 500GiB). Wins over CAPYCTL_MODEL_SOURCES_MAX and model_sources.max_bytes
--model-sources-path <DIR> — The directory downloads are kept under (default: the models directory). Wins over CAPYCTL_MODEL_SOURCES_PATH and model_sources.path
--hf-endpoint <URL> — The Hugging Face endpoint downloads use (https://, default https://huggingface.co). Wins over CAPYCTL_HF_ENDPOINT, HF_ENDPOINT and model_sources.huggingface_endpoint
--model-sources-plain-http <allowed|disabled> — Allow plain http:// URLs for HTTP model downloads on this run (default disabled; the download is still checked against its sha256). Wins over CAPYCTL_MODEL_SOURCES_PLAIN_HTTP and model_sources.plain_http
--trust-declared-digest <true|false> — Trust a local checkpoint’s declared canonical content_fingerprint without hashing it in full, true or false (default). Wins over CAPYCTL_TRUST_DECLARED_DIGEST and checkpoints.trust_declared_digest
--vllm-bin <PATH> — The vLLM executable this role runs as its local profile. Wins over CAPYCTL_VLLM_BIN and local_engine.vllm
--sglang-bin <PATH> — The SGLang interpreter this role runs as its local profile. Wins over CAPYCTL_SGLANG_BIN and local_engine.sglang
--tensorfold-bin <PATH> — The TensorFold executable (<venv>/bin/tensorfold) this role runs as its local profile. Wins over CAPYCTL_TENSORFOLD_BIN and local_engine.tensorfold
--llamacpp-bin <PATH> — The llama.cpp llama-server binary this role runs as its local profile. Wins over CAPYCTL_LLAMACPP_BIN and local_engine.llamacpp
--engine-fingerprint <TEXT> — The build fingerprint the local engine publishes (default: what <engine> --version prints). Wins over CAPYCTL_ENGINE_FINGERPRINT and local_engine.build_fingerprint
--engine-args <ARGS> — Host-fixed vLLM arguments of the local engine, one string. Wins over CAPYCTL_ENGINE_ARGS and local_engine.args
--deep-park <on|off> — Deep parking of the local engine, on (default) or off. Wins over CAPYCTL_DEEP_PARK and local_engine.deep_park
--trust-remote-code <true|false> — Whether the local engine may run checkpoint-supplied Python, true or false (default). Wins over CAPYCTL_TRUST_REMOTE_CODE and local_engine.trust_remote_code
--installation-drift <warn|refuse> — What a launch does when the local engine’s files changed, warn (default) or refuse. Wins over CAPYCTL_INSTALLATION_DRIFT and local_engine.installation_drift
--runtime-dir <DIR> — capyctl’s runtime directory (default: the managed copy in the state directory). Wins over CAPYCTL_RUNTIME_DIR and runtime_dir
--engine-ports <START-END> — The engines’ loopback port range, start-end (default 8100-8199). Wins over CAPYCTL_ENGINE_PORTS and resource_policy.endpoint_port_range
--cuda-home <DIR> — The CUDA toolkit directory of the local engine (its bin/ joins the engine PATH for JIT builds; default none). Wins over CAPYCTL_CUDA_HOME and local_engine.cuda_home
--peer-address <IP> — The address this host’s group peers reach it on, an IP address such as 192.0.2.10 (default none). Wins over CAPYCTL_PEER_ADDRESS and resource_policy.groups.peer_address
--rendezvous-ports <START-END> — The group rendezvous port range, start-end (default 25000-25099). Wins over CAPYCTL_RENDEZVOUS_PORTS and resource_policy.groups.rendezvous_port_range
--require-rdma <true|false> — Refuse group work on this host when RDMA tuning (memlock, infiniband) is missing (default false). Wins over CAPYCTL_REQUIRE_RDMA and resource_policy.groups.require_rdma
--kv-cache <SIZE> — The KV cache of the deployments standalone generates (for example 16GiB). Wins over CAPYCTL_KV_CACHE_BYTES and host.local_engine.kv_cache
--management-listen <ADDR:PORT> — Serve the management API on this loopback address for this run (default 127.0.0.1:7443). Wins over CAPYCTL_MANAGEMENT_ADDR and server.listeners.management.bind
--set <PATH=VALUE> — Set any setting of the role document for this run, by its YAML path (repeatable), e.g. –set shutdown.drain_timeout=45s. Wins over CAPYCTL_SET__ and the document; a setting that also has a named flag or variable must agree with it. Secrets cannot be set here

`capyctl start deployment`

Start a deployment’s engines

Usage: capyctl start deployment [OPTIONS] <DEPLOYMENT>

Arguments:

<DEPLOYMENT> — A deployment, by name or id

Options:

--initialize-timeout <DURATION> — How long the engine may take to load (for example 20m), instead of the deployment’s timeouts.initialize
--evict — Make room by parking or stopping idle deployments, and report which. If it cannot fit even then, nothing is touched and the start fails with exit code 4. Without it a start never evicts anything
--wait — Wait until every instance is ready; exit 0 only then. Exits 4 when there is no room, 13 when the launch fails, 10 on timeout and 15 when no host can take it, with the reason

`capyctl start instance`

Start one instance, <deployment>/<index>

Usage: capyctl start instance [OPTIONS] <INSTANCE>

Arguments:

<INSTANCE>

Options:

--initialize-timeout <DURATION> — How long the engine may take to load, instead of the deployment’s timeouts.initialize
--evict — Make room on its host by parking or stopping idle deployments, and report which
--wait — Wait for the start to finish; on failure print the reason

`capyctl init`

Write a starter configuration file for a server or a host

Usage: capyctl init <COMMAND>

Subcommands:

server — Write a starter server configuration
host — Write a starter host configuration

`capyctl init server`

Write a starter server configuration

Usage: capyctl init server

`capyctl init host`

Write a starter host configuration

Usage: capyctl init host

`capyctl invite`

Create a single-use invitation file that lets a GPU machine join the server. With --recover, let a revoked host rejoin as itself

Usage: capyctl invite [OPTIONS] <RESOURCE> [HOST]

Arguments:

<RESOURCE>

Possible values: host
<HOST> — The host: a new host’s name, or with --recover a revoked host’s name or id. The same as --name

Options:

--name <NAME> — The host’s name (instead of the positional argument)
--recover — Create a recovery invitation for a revoked host

`capyctl join`

Join this machine to a server with an invitation file. With --recover, rejoin a revoked host as itself; its state is kept

Usage: capyctl join [OPTIONS] --join-file <JOIN_FILE> <RESOURCE>

Arguments:

<RESOURCE>

Possible values: host

Options:

--join-file <JOIN_FILE> — The invitation file from capyctl invite host
--recover — Redeem a recovery invitation
--set <PATH=VALUE> — Set any setting of the role document for this run, by its YAML path (repeatable), e.g. –set shutdown.drain_timeout=45s. Wins over CAPYCTL_SET__ and the document; a setting that also has a named flag or variable must agree with it. Secrets cannot be set here

`capyctl list`

List hosts, deployments or engines as a table

Usage: capyctl list <COMMAND>

Subcommands:

hosts — Hosts joined to the server and whether they are connected
deployments — Deployments, their state and the hosts they run on
engines — Every host’s registered engines

`capyctl list hosts`

Hosts joined to the server and whether they are connected

Usage: capyctl list hosts

`capyctl list deployments`

Deployments, their state and the hosts they run on

Usage: capyctl list deployments

`capyctl list engines`

Every host’s registered engines

Usage: capyctl list engines

`capyctl inspect`

Print the full JSON record of a host or a deployment

Usage: capyctl inspect <COMMAND>

Subcommands:

host — A host’s full record
deployment — A deployment’s full record
config — A role’s configuration. Not available in this release

`capyctl inspect host`

A host’s full record

Usage: capyctl inspect host <HOST>

Arguments:

<HOST> — A host, by name or id

`capyctl inspect deployment`

A deployment’s full record

Usage: capyctl inspect deployment [OPTIONS] <DEPLOYMENT>

Arguments:

<DEPLOYMENT> — A deployment, by name or id

Options:

--effective-config — Include the configuration as resolved for launch

`capyctl inspect config`

A role’s configuration. Not available in this release

Usage: capyctl inspect config [OPTIONS]

Options:

--role <ROLE> — The role: server, host or standalone
--effective — Show it with defaults filled in

`capyctl doctor`

Check a host. Not available in this release

Usage: capyctl doctor <RESOURCE> <HOST>

Arguments:

<RESOURCE>

Possible values: host
<HOST> — A host, by name or id

`capyctl deploy`

Create a deployment from a YAML file, or update one

Usage: capyctl deploy <COMMAND>

Subcommands:

model — Deploy a model from a deployment file

`capyctl deploy model`

Deploy a model from a deployment file

Usage: capyctl deploy model [OPTIONS]

Options:

--file <FILE> — The deployment file (YAML)
--activate — Start it as soon as it is accepted
--wait — With --activate: wait until it is ready
--initialize-timeout <DURATION> — With --activate: how long the engine may take to load, instead of the deployment’s timeouts.initialize
--revision <N> — Update the existing deployment the file names. N is its current revision, as capyctl list deployments shows it. Changing only the instance count keeps running instances; any other change restarts them
--hf-endpoint <URL> — The Hugging Face endpoint an hf: reference without a commit is pinned against (https://, or a loopback http:// mirror). Wins over CAPYCTL_HF_ENDPOINT, HF_ENDPOINT and the role document’s model_sources.huggingface_endpoint
--engine-env <K=V> — An engine environment variable for this deployment, saved under engine_config.env (repeatable). Its name must match the profile’s approved environment. Also read from CAPYCTL_ENGINE_ENV (K=V;K=V); a flag wins over it. Shown in status; not secret storage

`capyctl status`

Show a deployment’s state and its instances

Usage: capyctl status <COMMAND>

Subcommands:

deployment — A deployment’s state and its instances

`capyctl status deployment`

A deployment’s state and its instances

Usage: capyctl status deployment [OPTIONS] <DEPLOYMENT>

Arguments:

<DEPLOYMENT> — A deployment, by name or id

Options:

--watch — Keep printing updates. Not available in this release

`capyctl park`

Park a deployment: free its GPU memory and keep it ready to wake. The next request for it wakes it

Usage: capyctl park <RESOURCE> <DEPLOYMENT>

Arguments:

<RESOURCE>

Possible values: deployment
<DEPLOYMENT> — A deployment, by name or id

`capyctl stop`

Stop a deployment’s engines, or one instance. The deployment is kept

Usage: capyctl stop <COMMAND>

Subcommands:

deployment — Stop every engine of a deployment
instance — Stop one instance, <deployment>/<index>

`capyctl stop deployment`

Stop every engine of a deployment

Usage: capyctl stop deployment <DEPLOYMENT>

Arguments:

<DEPLOYMENT> — A deployment, by name or id

`capyctl stop instance`

Stop one instance, <deployment>/<index>

Usage: capyctl stop instance <INSTANCE>

Arguments:

<INSTANCE>

`capyctl preinitialize`

Start a deployment, check it answers, then park it, so its first request only has to wake it

Usage: capyctl preinitialize <RESOURCE> <DEPLOYMENT>

Arguments:

<RESOURCE>

Possible values: deployment
<DEPLOYMENT> — A deployment, by name or id

`capyctl delete`

Delete a deployment and its routes once its engines are confirmed stopped. Model files and caches on hosts are never touched

Usage: capyctl delete <COMMAND>

Subcommands:

deployment — Delete a deployment. Refused while any of its engines may still be running or starting, unless --stop is given

`capyctl delete deployment`

Delete a deployment. Refused while any of its engines may still be running or starting, unless --stop is given

Usage: capyctl delete deployment [OPTIONS] <DEPLOYMENT>

Arguments:

<DEPLOYMENT> — A deployment, by name or id

Options:

--stop — Stop it first, wait until its engines are confirmed gone, then delete. If that cannot be confirmed yet it reports pending; run it again with the same --request-id to continue

`capyctl validate`

Check a configuration file without starting anything

Usage: capyctl validate <COMMAND>

Subcommands:

config — Check one server, host, standalone or deployment file

`capyctl validate config`

Check one server, host, standalone or deployment file

Usage: capyctl validate config [OPTIONS] --file <FILE>

Options:

--file <FILE> — The file to check
--host <FILE> — The host document a deployment file is resolved against; for a group deployment, repeat it once per host in placement.hosts
--set <PATH=VALUE> — Validate a role document with this setting changed, as start would (repeatable), e.g. –set shutdown.drain_timeout=45s

`capyctl config`

Show the settings a role would run with and where each came from

Usage: capyctl config <COMMAND>

Subcommands:

show — Print the effective configuration of a role with each value’s source (default, yaml, env, flag or set). The role document is –config (or CAPYCTL_CONFIG), else that of the role on this machine

`capyctl config show`

Print the effective configuration of a role with each value’s source (default, yaml, env, flag or set). The role document is –config (or CAPYCTL_CONFIG), else that of the role on this machine

Usage: capyctl config show [OPTIONS]

Options:

--role <ROLE> — The role: server, host or standalone (default: the kind of the named document, else the role on this machine, else standalone)
--set <PATH=VALUE> — Show the configuration with this setting changed (repeatable)

`capyctl drain`

Stop every engine on a host and keep its deployments; they start again when a request needs them. Stopping the capyctl service does not do this

Usage: capyctl drain <COMMAND>

Subcommands:

host — Drain a host through the server
standalone — Drain the engines of the standalone instance on this machine

`capyctl drain host`

Drain a host through the server

Usage: capyctl drain host [OPTIONS] <HOST>

Arguments:

<HOST> — A host, by name or id

Options:

--wait — For an offline host, wait until it reconnects and its engines stop, instead of returning at once

`capyctl drain standalone`

Drain the engines of the standalone instance on this machine

Usage: capyctl drain standalone

`capyctl revoke`

Disconnect a host for good. Its capyctl process exits with code 14; its engines keep running but get no more requests, and their GPU memory stays counted as used. Bring it back with invite host --recover and join host --recover

Usage: capyctl revoke <COMMAND>

Subcommands:

host — Revoke a host. Revoking it again changes nothing

`capyctl revoke host`

Revoke a host. Revoking it again changes nothing

Usage: capyctl revoke host <HOST>

Arguments:

<HOST> — A host, by name or id

`capyctl prune`

Remove downloaded model copies that no deployment uses from this machine’s model store. Deleting a deployment never does this

Usage: capyctl prune <COMMAND>

Subcommands:

sources — List the copies under <model store>/sources that no deployment uses; remove them with --apply. A download in progress is never touched

`capyctl prune sources`

List the copies under <model store>/sources that no deployment uses; remove them with --apply. A download in progress is never touched

Usage: capyctl prune sources [OPTIONS] --host-config <FILE>

Options:

--host-config <FILE> — The host document naming the model store to prune
--apply — Remove the unreferenced copies instead of listing them
--referenced-file <FILE> — The server’s GET /management/v1/model-sources answer, saved to a file, for a host that cannot reach the management API itself

`capyctl engine`

Register, list or remove the vLLM, SGLang, TensorFold and llama.cpp installations on this machine. Each one becomes a runtime profile deployments can name

Usage: capyctl engine <COMMAND>

Subcommands:

detect — List vLLM, SGLang, TensorFold and llama.cpp installations on this machine (reads metadata only)
add — Register an installation as a runtime profile and publish it
list — This machine’s runtime profiles and whether the server accepted them
remove — Remove a runtime profile
flags — Print which engine options and environment variables CapyCTL owns, reserves, gates behind an approval, or passes unchanged, and why

`capyctl engine detect`

List vLLM, SGLang, TensorFold and llama.cpp installations on this machine (reads metadata only)

Usage: capyctl engine detect [OPTIONS]

Options:

--path <PATHS> — Also scan this directory (repeatable)

`capyctl engine add`

Usage: capyctl engine add [OPTIONS] [PATH]

Arguments:

<PATH> — A venv directory, its bin/vllm, bin/tensorfold or bin/python3, or a llama-server binary or the directory holding it. Omit to pick interactively

Options:

--custom <EXECUTABLE> — A custom engine: the program to run, started with the arguments its –manifest states. Needs –name and –manifest; nothing is executed when it is registered
--manifest <FILE> — A custom engine’s manifest (YAML, at most 64 KiB): its API, the argument template and the optional health path and idle signal. Read once and copied into the profile
--yes — Register a custom engine without asking (needed without a terminal)
--name <NAME> — The profile name (default: the engine’s name; required with –custom)
--deep-park <DEEP_PARK> — Record deep parking enabled or disabled (default: enabled unless the capability probe reports it missing)

Possible values: enabled, disabled
--drift <DRIFT> — What a launch does when the installation changed since registration

Default value: warn

Possible values: warn, refuse
--arg <ARGS> — An engine argument added to every launch with this profile (repeatable; not with –custom)
--approve-option <OPTION> — A security-sensitive engine option deployments may pass in engine_config.extra_args, such as –drafter (repeatable). Written as security.approved_options. Not with –custom
--approve-path <DIR> — A directory an approved path option may name, such as a drafter’s parent directory (repeatable, absolute). Written as security.approved_paths. Not with –custom
--env <K=V> — An engine environment variable every launch with this profile sets (repeatable). Also read from CAPYCTL_ENGINE_ADD_ENV (K=V;K=V); a flag wins over it. Shown in status; not secret storage
--approve-env <GLOB> — A name, or a name ending in *, deployments may set in engine_config.env, such as MBX_* (repeatable). Written as security.approved_env. Also read from CAPYCTL_APPROVE_ENV (GLOB;GLOB), used only when no –approve-env is given
--allow-remote-code — Let deployments set engine_config.trust_remote_code: true, which runs the Python a checkpoint ships with (vLLM and SGLang only). Written as security.trust_remote_code. Not with –custom

`capyctl engine list`

This machine’s runtime profiles and whether the server accepted them

Usage: capyctl engine list

`capyctl engine remove`

Remove a runtime profile

Usage: capyctl engine remove [OPTIONS] <NAME>

Arguments:

<NAME> — The profile name

Options:

--drain — Stop the deployments on this machine that use it first

`capyctl engine flags`

Print which engine options and environment variables CapyCTL owns, reserves, gates behind an approval, or passes unchanged, and why

Usage: capyctl engine flags <FAMILY>

Arguments:

<FAMILY> — The engine family: vllm, sglang, tensorfold or llamacpp

Options:

--version <V> — The engine version the table is read for; recorded in the output

`capyctl version`

Print this build’s version and, for a release build, the commit it was built from. --version prints the version line only

Usage: capyctl version