Commands for running code inside a box and observing it. For the runtime environment these drop into, see Environment.

​
exec

Run a command in a box 
zomg exec <BOX_NAME> [<CMD>...] [options]
Argument / optionDescription
<BOX_NAME>Box name (use - for ephemeral)
--user <USER>Run command as a project user
<CMD>Command and arguments (use -- separator) (repeatable)
--env <ENV>Environment variable as KEY=VALUE (repeatable)
--wd <CWD>Working directory inside the box
--shRun command via shell (treat args as a shell string)
--bgRun in background (detached, returns PID)
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Run a command (foreground, waits for result)
zomg exec my-box -- python3 -V

# Run with environment variables
zomg exec my-box --env FOO=bar -- printenv FOO

# Run as a project user with shared /home/<user>
zomg exec --user alice my-box -- id

# Run in background (returns PID immediately)
zomg exec my-box --bg -- python3 -m http.server 8080

# Pipe stdin to a command
echo "hello" | zomg exec my-box -- tee /tmp/hello.txt

# Ephemeral box (auto-created, auto-deleted)
zomg exec - -- python3 -c "print('temporary!')"

# Exit codes are preserved
zomg exec my-box -- false; echo $?

​
ps

Show processes in a box 
zomg ps <BOX_NAME> [<CMD>...] [options]
Argument / optionDescription
<BOX_NAME>Box name (use - for ephemeral)
--user <USER>Run command as a project user
<CMD>Command and arguments (use -- separator) (repeatable)
--env <ENV>Environment variable as KEY=VALUE (repeatable)
--wd <CWD>Working directory inside the box
--shRun command via shell (treat args as a shell string)
--bgRun in background (detached, returns PID)
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Show all processes
zomg ps my-box

# Show process tree
zomg ps my-box -- auxf

​
logs

View logs for a process in a box 
zomg logs <BOX_NAME> [options]
Argument / optionDescription
<BOX_NAME>Box ref.
--pid <PID>Process ID to view logs for (required)
-l, --lines <LINES>Number of lines to show (most recent) Defaults to 100.
-f, --followFollow logs in real-time (like tail -f)
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# View last 100 lines for a process
zomg logs my-box --pid 1234

# Follow logs in real-time
zomg logs my-box --pid 1234 --follow

# Show only last 50 lines
zomg logs my-box --pid 1234 --lines 50

# Search persisted logs across services, boxes, and control-plane components
zomg observability logs my-box --q error --since 1h

​
observability

Search and tail persisted deployment logs 
zomg observability <command>
SubcommandDescription
logsSearch and tail Loki-backed logs
tracesSearch Tempo-backed traces
traceFetch a single Tempo-backed trace by ID
agent-envPrint Claude/Codex OpenTelemetry configuration for agent sessions
# Search recent logs across the whole deployment
zomg observability logs --q error --since 1h

# Search one box or one managed service
zomg observability logs my-box --q "startup complete"
zomg observability logs my-box --service web --since 30m

# Follow Loki-backed logs for coding agents
zomg observability logs my-box --service web --follow --interval 2

# Machine-readable output
zomg observability logs --level ERROR --limit 50 --json

​
logs

Search and tail Loki-backed logs 
zomg observability logs [<BOX_NAME>] [options]
Argument / optionDescription
<BOX_NAME>Optional box name to filter. When set, defaults —project to the current project
-p, --project <PROJECT>Project filter. Omit with no box to search across all projects and control-plane logs
-s, --service <SERVICE>Managed service label filter
--pid <PID>Background/service process PID label filter
-q, --q <Q>Text search applied to log lines
--level <LEVEL>Case-sensitive level label filter, for example INFO, WARN, ERROR, info, warn, error
--job <JOB>Loki job label filter, for example zomg-service, zomg-box-file, kubernetes-pod
--component <COMPONENT>Component label filter, for example service-log or box-file-log
--since <SINCE>Lookback window such as 5m, 1h, 2d, 1w. Defaults to 1h.
-l, --limit <LIMIT>Maximum log entries returned per query. Defaults to 200.
-f, --followPoll continuously and print new entries
--interval <INTERVAL>Follow polling interval in seconds. Defaults to 2.
--rawPrint raw log lines only
-j, --jsonPrint JSON response for one-shot queries or JSON lines while following

​
traces

Search Tempo-backed traces 
zomg observability traces [<BOX_NAME>] [options]
Argument / optionDescription
<BOX_NAME>Optional box name to filter. When set, defaults —project to the current project
-p, --project <PROJECT>Project filter. Omit with no box to search across all projects and control-plane traces
--agent <AGENT>Agent provider filter, for example claude or codex
--session <AGENT_SESSION_ID>Agent session ID filter
--service-name <SERVICE_NAME>service.name filter
--model <MODEL>Model attribute filter
--tool <TOOL>Tool attribute filter
-q, --q <Q>Raw TraceQL query. When set, attribute filters are ignored by Tempo
--since <SINCE>Lookback window such as 5m, 1h, 2d, 1w. Defaults to 1h.
-l, --limit <LIMIT>Maximum traces returned. Defaults to 20.
--min-duration <MIN_DURATION>Minimum trace duration, for example 100ms or 5s
--max-duration <MAX_DURATION>Maximum trace duration, for example 500ms or 10s
-j, --jsonPrint the raw JSON response

​
trace

Fetch a single Tempo-backed trace by ID 
zomg observability trace <TRACE_ID> [options]
Argument / optionDescription
<TRACE_ID>Trace ID
--since <SINCE>Optional lookback window to bound Tempo trace lookup
-j, --jsonPrint the raw JSON response

​
agent-env

Print Claude/Codex OpenTelemetry configuration for agent sessions 
zomg observability agent-env [options]
Argument / optionDescription
--agent <AGENT>Agent configuration to print: claude, codex, or all. Defaults to all.
-p, --project <PROJECT>Project value to include in resource attributes
--box-name <BOX_NAME>Box value to include in resource attributes

​
console

Open an interactive shell or run a command with a TTY 
zomg console <BOX_NAME> [options]
Argument / optionDescription
<BOX_NAME>Box name (use - for ephemeral)
--ttyForce interactive TTY mode
--no-ttyDisable interactive TTY mode (pipe/script friendly)
--rawForce local terminal raw mode
--no-rawDisable local terminal raw mode
--term <TERM>TERM value inside console session (default: inherit TERM or xterm-256color)
--user <USER>Run console as a project user
--command <COMMAND>Command to run instead of login shell
--wd <CWD>Working directory inside the box
--log-console-debugPrint console transport mode details to stderr
-p, --project <PROJECT>Target project.
# Open interactive shell
zomg console my-box

# Open as a project user with shared /home/<user>
zomg console --user alice my-box

# Run a specific command with TTY
zomg console my-box --command "bash -lc 'vim /etc/hosts'"

# Disable TTY/raw mode for scripting
zomg console my-box --no-tty --command "env | sort"

# Ephemeral console (auto-deleted on exit)
zomg console -

​
ssh

Connect to a box through the SSH gateway 
zomg ssh <BOX_NAME> [<SSH_ARGS>...] [options]
Argument / optionDescription
<BOX_NAME>Box to connect to (supports qualified refs like project:box)
-p, --project <PROJECT>Target project.
--host <HOST>SSH gateway hostname
--port <PORT>SSH gateway port. Defaults to 2222.
--infoPrint the resolved ssh command and exit (do not connect)
<SSH_ARGS>Extra args passed to ssh after -- (e.g. -- -v -i ~/.ssh/id_ed25519) (repeatable)
# Connect via SSH gateway
zomg ssh my-box

# Show resolved ssh command without connecting
zomg ssh my-box --info

# Pass extra SSH flags
zomg ssh my-box -- -v -i ~/.ssh/custom_key

​
port

Inspect and wait on listening ports in a box 
zomg port <command>
SubcommandDescription
listList listening ports in a box
waitWait for a port to start listening
# List listening ports
zomg port list my-box

# Wait for PostgreSQL to start (60s timeout)
zomg port wait my-box 5432

# Wait for UDP port with custom timeout
zomg port wait my-box 53 --udp --timeout 30

​
list

List listening ports in a box 
zomg port list <BOX_NAME> [options]
Argument / optionDescription
<BOX_NAME>Box ref.
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
--tcpShow only TCP ports
--udpShow only UDP ports

​
wait

Wait for a port to start listening 
zomg port wait <BOX_NAME> <PORT> [options]
Argument / optionDescription
<BOX_NAME>Box ref.
<PORT>Port number to wait for
-p, --project <PROJECT>Target project.
--tcpWait for TCP port (default)
--udpWait for UDP port
--timeout <TIMEOUT>Timeout in seconds (0 = wait forever) Defaults to 60.
--interval <INTERVAL>Poll interval in seconds. Defaults to 1.
-j, --jsonPrint the JSON response.