Run commands

How envctl exec runs a command in an environment: syncing first, streaming, exit codes, timeouts and results.

envctl exec [--timeout N] [--no-sync] [--dir path] <environment> -- <command> [args...]

<environment> is a name like linux-build-3f2a or an ID like env_…. Everything after -- runs in the environment, in the template’s working directory (/work for linux-build) unless you pass --dir.

What happens

1. Sync first

   Your sandbox syncs every share it writes and waits for each receiver’s acknowledgement, so the command sees your latest edits. If the environment was just created, a sync waits a few seconds for the tailnet path to form. Skip this with --no-sync.

2. Run and stream

   The command runs over the tailnet. Standard output and error stream back as they happen, and Ctrl-C stops it.

3. Results come back

   Before it reports the exit code, the environment syncs its out shares and waits for your sandbox to acknowledge. Files written to /work/out are on your machine when exec returns.

4. Exit

   envctl exits with the command’s exit code.

Shell features

The command isn’t run through a shell. For pipes, && or cd, wrap it:

envctl exec linux-build-3f2a -- sh -c 'cd /work/api && go test ./... | tee out/test.log'

Timeouts

envctl exec --timeout 300 linux-build-3f2a -- make integration

stops the command after 300 seconds and exits with code 124. Without --timeout, a command runs until it finishes or the environment reaches its hard limit.

Exit codes

Code	Meaning
The command’s own	The command ran and exited with it
124	--timeout stopped the command
1	envctl couldn’t run it: the environment isn’t reachable, or the first sync failed
2	The command line was wrong

Idle and the log

An environment doesn’t go idle while a command runs in it. Every command is recorded with its exit code and duration, and the console shows them on the environment’s page.