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 
4kr exec <FORK> [<CMD>...] [options]
Argument / optionDescription
<FORK>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)
4kr exec my-box -- python3 -V

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

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

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

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

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

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

​
ps

Show processes in a box 
4kr ps <FORK> [<CMD>...] [options]
Argument / optionDescription
<FORK>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
4kr ps my-box

# Show process tree
4kr ps my-box -- auxf

​
logs

View logs for a process in a box 
4kr logs <FORK> [options]
Argument / optionDescription
<FORK>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
4kr logs my-box --pid 1234

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

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

​
console

Open an interactive shell or run a command with a TTY 
4kr console <FORK> [options]
Argument / optionDescription
<FORK>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
4kr console my-box

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

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

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

# Ephemeral console (auto-deleted on exit)
4kr console -

​
ssh

Connect to a box through the SSH gateway 
4kr ssh <FORK> [<SSH_ARGS>...] [options]
Argument / optionDescription
<FORK>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
4kr ssh my-box

# Show resolved ssh command without connecting
4kr ssh my-box --info

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

​
port

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

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

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

​
list

List listening ports in a box 
4kr port list <FORK> [options]
Argument / optionDescription
<FORK>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 
4kr port wait <FORK> <PORT> [options]
Argument / optionDescription
<FORK>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.