Execution

An exec is one command run inside a box. Foreground exec keeps output and exit code in your current terminal. Background exec lets the work continue after you disconnect.

Foreground

⌘Copysys9 run box exec <box-id> [flags] <command...>

Add -- only when the remote command itself starts with flag-like tokens and you need to stop local flag parsing.

Common flags:

• --deadline
• --user
• --workdir
• -e KEY=VALUE
• -i
• -t

Foreground exec stays attached to the current connection. Use -i to keep local stdin open. Add -t for terminal programs such as shells or TUIs.

--deadline takes a duration such as 30m. Without it, a foreground exec may run for up to 12 hours.

Prefer exec flags over shell glue when only the command context changes:

⌘Copysys9 run box exec my-box --workdir /work/app git status
sys9 run box exec my-box -e NODE_ENV=test printenv NODE_ENV

Save shell wrappers for commands that actually need shell syntax such as pipes, redirections, or here-docs.

box exec streams remote output directly and returns the remote exit code. It does not support --json or --output json.

Background

⌘Copysys9 run box exec-bg <box-id> [flags] <command...>
sys9 run box exec-bg pull-output <exec-id> [--wait <duration>] [--cursor <token> | --from-start]
sys9 run box exec-bg write-stdin <exec-id> [--eof]
sys9 run box exec-bg kill <exec-id>

Background exec starts work and prints the exec_id, current state, idle deadline, and the command to read output. Background exec works well for servers, watchers, long tests, or other work you keep checking on.

It accepts the same flags as foreground exec except -t. -i keeps a stdin channel open for later write-stdin calls.

Use JSON when a script needs the full exec view:

⌘Copysys9 run --json box exec-bg my-box sleep 30

pull-output is also a stream command. It renders mixed background output and rejects --json.

write-stdin and kill print short OK: confirmations by default and support JSON for automation. One write-stdin call sends at most 32 KiB.

Background lifetime

A background exec stays alive as long as someone keeps reading it.

• Each exec has an idle deadline one hour ahead. Every successful pull-output or write-stdin moves it another hour out.
• If the idle deadline passes with no read, run9 cancels the exec with the reason idle_timeout.
• --deadline <duration> adds a fixed upper limit that reads cannot extend. Without it, there is no total time limit.

Output is kept for reading, not forever:

• The most recent 20 MiB of mixed output can be read back. Older output is dropped, and pull-output says so with a clear notice.
• After the exec ends, pull-output keeps working for one hour.
• The exec’s state, exit code, and timing stay in history for seven days.

For unattended work, call pull-output on a schedule and write the results you need to keep to a file in the box.

History

⌘Copysys9 run execs ls [--box <box-id>] [--state <state>] [--order asc|desc] [--limit <n>] [--cursor <token>]
sys9 run execs inspect <exec-id>
sys9 run execs log <exec-id> [--file <path>]
sys9 run box execs ls <box-id> [--limit <n>] [--cursor <token>]
sys9 run box execs inspect <exec-id>

Use history when you need the state, command, exit code, or output cursor for an exec. execs ls covers the whole current project, newest first, and can also filter by creator or by a time window with --accepted-after and --accepted-before. box execs ls is the same list for one box.

execs ls prints a table by default. If there is another page, it prints the next cursor command. Use --json to include items and next_cursor in stdout.

execs log prints the saved log of a foreground exec as raw bytes, or writes it to a local file with --file. Logs are kept for a limited time, and very large ones are trimmed.