Processes
Run and manage processes inside a sandbox from the shell — one-off commands, background servers, logs, attach, stop, and autostart.
tektona sandbox process (aliases proc, ps, p) runs and manages processes
inside a sandbox. Processes are sandbox-owned: they survive client disconnects
and are addressable later by ULID or --name. For the concepts and end-to-end
examples, see the Processes guide.
Inside a sandbox the same command group is available as tektonactl process
(aliases proc, ps, p) with the sandbox id dropped — see tektonactl.
run
tektona sandbox process run <sandbox-id> [flags] -- <command> [args…]Runs a command inside the sandbox. Everything after -- is the command. run
waits by default, streaming stdout/stderr and exiting with the remote exit
code; local stdin is piped through when not a TTY. -d/--detach starts the
process and prints its id instead of waiting.
The command is an argument vector, not a shell line — shell syntax like &&,
pipes, and globs is not interpreted. To run a shell one-liner, pass
-s/--shell: the command line runs in a shell inside the sandbox (bash when
the image has it, sh otherwise).
tektona sandbox process run 01J9F3ZK7QW4B2Y8N5T1QAZ6RX -- npm test
tektona sandbox process run 01J9F3ZK7QW4B2Y8N5T1QAZ6RX -d --name dev-server -- npm run dev
tektona sandbox process run 01J9F3ZK7QW4B2Y8N5T1QAZ6RX -t -- bash
tektona sandbox process run 01J9F3ZK7QW4B2Y8N5T1QAZ6RX -s -- 'apt update && apt install -y nginx'| Flag | Default | Purpose |
|---|---|---|
-d, --detach | false | Start and print the id without waiting. |
-t, --tty | false | Allocate a PTY (raw-mode interactive session). |
-s, --shell | false | Run the command line through a shell in the sandbox (bash if available, else sh), enabling &&, pipes, and globs. |
-n, --name | — | Name the process (required for --autostart); unique among running processes. A memorable name is generated when omitted. |
--env K=V | — | Environment variable; repeatable. |
--cwd | — | Working directory. |
--user | image default | Run-as Linux user. |
--timeout | 0 (none) | Kill the whole process group after this Go-style duration; sub-second values round up to the 1s minimum. |
--prevent-auto-pause | false | Keep the sandbox awake while the process runs. |
--on-hibernate | preserve | Behavior across a hibernate pause: preserve, stop, or restart_after_resume. Doesn't apply to a disk-only suspend, which cold-boots the guest (use --autostart to relaunch there). |
--autostart | false | Persist the definition and relaunch it on every boot (requires --name). |
--max-log-bytes | sandbox default | Cap retained log bytes; 0 disables logging. |
--resume | false | Resume the sandbox first if it is paused. |
Ctrl-C in run forwards SIGINT to the remote process; detach is only ever
explicit (-d), never a Ctrl-C side effect.
ls
tektona sandbox process ls <sandbox-id> [-a/--all] [--autostart] [--resume]Lists process instances, newest first (alias list). By default only running
instances are shown; a footer notes how many finished ones were hidden. The
AUTOSTART column shows * for instances managed by autostart. Pass -a/--all
to also show finished instances — running first, then a blank line, then the
finished ones (each group newest first). --autostart lists the persisted
autostart definitions instead, each with its last launch outcome; this is the
only view that lists definitions as entries.
get
tektona sandbox process get <sandbox-id> <ref> [--resume]Shows one process by ULID or name (aliases info, show).
logs
tektona sandbox process logs <sandbox-id> <ref> [-f] [-n/--tail N] [--resume]Fetches the buffered log, or tails live with -f/--follow until the process
ends. -n, --tail N limits to the last N lines (as in tail -n). Ctrl-C stops
tailing only. Fails
for a process started with --max-log-bytes 0 (logging disabled).
attach
tektona sandbox process attach <sandbox-id> <ref> [-t] [--resume]Attaches interactively: replays a screenful of recent output, then streams live. Multiple clients may attach at once. Detaching does not stop the process.
stop
tektona sandbox process stop <sandbox-id> <ref> [--force] [--resume]Stops the process: SIGTERM → grace → SIGKILL, delivered to the whole process
group. --force skips straight to SIGKILL.
signal
tektona sandbox process signal <sandbox-id> <ref> <signal> [--resume]Delivers one signal to the process group. Accepted (with or without the SIG
prefix): SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGKILL, SIGUSR1,
SIGUSR2, SIGSTOP, SIGCONT.
autostart
tektona sandbox process autostart <sandbox-id> <ref> on|off [--resume]Enables or disables the persisted autostart definition. off sticks — the
process won't relaunch on the next boot until turned back on.
JSON output
Pass -o json (the global output flag) to run -d, get, and ls (including
ls --autostart) to get machine-readable output instead of a table — useful for
CI and scripting. run without -d, logs, and attach stream their output
and ignore the flag. The JSON field names match the HTTP API's process resource;
optional fields (exit_code, finish_reason, restarted_from, signal,
error, …) are omitted when empty, so treat an absent key as null.
Paused sandboxes
Every subcommand except run returns a conflict on a paused sandbox unless you
pass --resume, so a status check never silently costs a resume. run always
resumes the sandbox to run your command.
tektonactl process
Inside a sandbox, tektonactl process (aliases proc, ps, p) exposes the same
group minus the sandbox id — it targets its own sandbox. It's the primary way an
in-sandbox agent runs background work.
tektonactl process run -d --name dev-server -- npm run dev
tektonactl process ls
tektonactl process get dev-server
tektonactl process logs dev-server -f
tektonactl process attach dev-server
tektonactl process stop dev-server
tektonactl process signal dev-server SIGHUPrun takes the same flags as the tektona variant (--tty, -n/--name, --env,
--cwd, --user, --timeout, --prevent-auto-pause, --on-hibernate,
--max-log-bytes). It acts on the same processes as tektona sandbox process,
so anything started here is visible and controllable from outside, and vice
versa. Reach it from outside with tektona ssh <id> -- tektonactl process ….