Catalog of every terok-executor subcommand and its handler.
The COMMANDS tree at the bottom is the authoritative registry;
higher-level frontends (terok) import it to wire the same commands
into their own CLI without duplicating argument definitions.
CommandDef /
ArgDef /
CommandTree are imported from
terok-util so the whole stack shares one vocabulary — adding new
verbs in sandbox flows into executor's tree automatically without an
overlay update.
RUN_COMMAND = CommandDef(name='run', help='Run an agent in a hardened container', handler=_handle_run, args=(ArgDef(name='agent', help='Agent name (claude, codex, vibe, ...)'), ArgDef(name='repo', nargs='?', default='.', help='Local path or git URL (default: .)'), ArgDef(name='-p', dest='prompt', help='Prompt for headless mode'), ArgDef(name='-m', dest='model', help='Model override'), ArgDef(name='--max-turns', type=int, help='Maximum agent turns'), ArgDef(name='--timeout', type=int, default=1800, help='Timeout in seconds (default: 1800)'), ArgDef(name='--interactive', action='store_true', help='CLI mode (user logs in)'), ArgDef(name='--web', action='store_true', help='Toad web mode'), ArgDef(name='--port', type=int, help='Port for web mode (auto-allocated if omitted)'), ArgDef(name='--gate', action='store_true', default=True, help='Use gate (default)'), ArgDef(name='--no-gate', action='store_true', help='Disable gate (direct network)'), ArgDef(name='--branch', help='Git branch to check out'), ArgDef(name='--name', help='Container name override'), ArgDef(name='--restricted', action='store_true', help='Restrict agent permissions (no auto-approve, no-new-privileges)'), ArgDef(name='--gpu', action='store_true', help='Enable GPU passthrough'), ArgDef(name='--memory', help='Container memory limit (e.g. 4g, 512m)'), ArgDef(name='--cpus', help='Container CPU limit (e.g. 2.0, 0.5)'), ArgDef(name='--git-identity-from-host', action='store_true', help='Use host git config user.name/email as human committer identity'), ArgDef(name='--shared-dir', help='Host directory to mount as shared IPC space'), ArgDef(name='--shared-mount', default='/shared', help='Container mount point for shared dir (default: /shared)'), ArgDef(name='--base', default=DEFAULT_BASE_IMAGE, help=f'Base OS image (default: {DEFAULT_BASE_IMAGE})'), ArgDef(name='--family', default=None, help='Override package family for unknown base images (deb or rpm)'), ArgDef(name='--timezone', default=None, help="IANA timezone for the container (e.g. 'Europe/Prague', 'UTC'). Default: follow the host."), ArgDef(name='--yes', action='store_true', dest='yes', help='Accept all first-run prerequisite prompts without asking'), ArgDef(name='--no-preflight', action='store_true', dest='no_preflight', help='Skip prerequisite checks entirely (caller manages setup)')))
module-attribute
AUTH_COMMAND = CommandDef(name='auth', help='Authenticate an agent', handler=_handle_auth, args=(ArgDef(name='agent', help='Agent or tool name (claude, codex, gh, ...)'), ArgDef(name='--api-key', help='Store an API key directly (skip interactive auth)'), ArgDef(name='--base-image', help=f'Override the L1 base image (default: image.base_image from config.yml, else {DEFAULT_BASE_IMAGE})')))
module-attribute
AGENTS_COMMAND = CommandDef(name='agents', help='Inspect the agent roster and set the build-time default selection', children=(CommandDef(name='list', help='List registered agents (use --all to include tools like gh, glab)', handler=_handle_agents_list, args=(ArgDef(name='--all', action='store_true', dest='show_all', help='Include tools (gh, glab)'),)), CommandDef(name='set', help='Set the global image.agents default in config.yml (interactive when no arg)', handler=_handle_agents_set, args=(ArgDef(name='selection', nargs='?', default=None, help='Agent selection in the executor\'s canonical grammar: "all", a comma list ("claude,vibe"), or "all,-name" to exclude one ("all,-vibe"). Interactive picker when omitted.'),))))
module-attribute
BUILD_COMMAND = CommandDef(name='build', help='Build L0+L1 container images', handler=_handle_build, args=(ArgDef(name='--base', default=DEFAULT_BASE_IMAGE, help=f'Base OS image (default: {DEFAULT_BASE_IMAGE})'), ArgDef(name='--family', default=None, help='Override package family for unknown base images (deb or rpm)'), ArgDef(name='--agents', default='all', help='Comma-separated roster entries to install, or "all" (default).'), ArgDef(name='--rebuild', action='store_true', help='Force rebuild (cache bust)'), ArgDef(name='--full-rebuild', action='store_true', help='Force --no-cache --pull=always'), ArgDef(name='--sidecar', action='store_true', help='Also build sidecar L1 (CodeRabbit)')))
module-attribute
ACP_COMMAND = CommandDef(name='acp', help='Run the per-container ACP host-proxy daemon', handler=_handle_acp, args=(ArgDef(name='container_name', help='Name of the running container to aggregate'), ArgDef(name='socket_path', help='Path to bind the ACP listener socket on')))
module-attribute
LIST_COMMAND = CommandDef(name='list', help='List running containers', handler=_handle_list)
module-attribute
SHOW_CONFIG_COMMAND = CommandDef(name='show-config', help='Print the effective SandboxConfig (diffable against higher-layer orchestrators)', handler=_handle_show_config)
module-attribute
STOP_COMMAND = CommandDef(name='stop', help='Stop a running container', handler=_handle_stop, args=(ArgDef(name='name', help='Container name'),))
module-attribute
SETUP_COMMAND = CommandDef(name='setup', help='Install sandbox services + container images (first-run bootstrap)', handler=_handle_setup, args=(ArgDef(name='--check', action='store_true', help='Report status without installing anything; exit non-zero if incomplete'), ArgDef(name='--no-sandbox', action='store_true', dest='no_sandbox', help='Skip sandbox setup (shield hooks, gate, and credentials-DB provisioning)'), ArgDef(name='--no-images', action='store_true', dest='no_images', help='Skip the L0+L1 container image build'), ArgDef(name='--base', default=DEFAULT_BASE_IMAGE, help=f'Base OS image to build L0+L1 on top of (default: {DEFAULT_BASE_IMAGE})'), ArgDef(name='--family', default=None, help='Override package family for unknown base images (deb or rpm)')))
module-attribute
UNINSTALL_COMMAND = CommandDef(name='uninstall', help='Remove sandbox services + container images (mirror of setup)', handler=_handle_uninstall, args=(ArgDef(name='--no-sandbox', action='store_true', dest='no_sandbox', help='Skip the shield+gate uninstall'), ArgDef(name='--keep-images', action='store_true', dest='keep_images', help='Keep the L0+L1 image cache so a re-install skips the rebuild'), ArgDef(name='--base', default=DEFAULT_BASE_IMAGE, help=f'Base OS image whose L0+L1 cache should be removed (default: {DEFAULT_BASE_IMAGE})')))
module-attribute
COMMANDS = (RUN_COMMAND, RUN_TOOL_COMMAND, AUTH_COMMAND, AGENTS_COMMAND, BUILD_COMMAND, SETUP_COMMAND, UNINSTALL_COMMAND, LIST_COMMAND, STOP_COMMAND, SHOW_CONFIG_COMMAND, ACP_COMMAND)
module-attribute