Skip to content

Exec and shell#

Two different things run commands, and they run them in different places.

Agent sandbox Project shell sandbox
Command nexusctl sandbox exec / sandbox shell nexusctl shell exec
Runs in A specific sandbox you created A shared per-project sandbox the platform manages
Use it to Debug or drive a running agent Run ad-hoc commands with the project's policy and credentials
Transport WebSocket, streaming, with optional TTY Request/response, one shot
Requires Project ADMIN role, sandbox in started state Project access

Exec into an agent sandbox#

nexusctl sandbox exec nightly-refactor --project production -- ls -la /workspace

-- separates the remote command from the CLI's own flags. stdout and stderr stream back as they are produced, and the remote command's exit code becomes the exit code of nexusctl, so this composes in scripts:

if ! nexusctl sandbox exec nightly-refactor --project production \
     -- test -f /workspace/report.md; then
  echo "agent has not produced a report yet"
fi

The sandbox must be in started state with its supervisor connected. Exec against a stopped or error sandbox fails rather than starting it.

Passing stdin#

echo '{"task":"summarize"}' | nexusctl sandbox exec nightly-refactor \
  --project production -i -- /usr/local/bin/handle-task

stdin EOF is not forwarded

A command that waits for end-of-input — a bare cat, for example — hangs. Use a finite-length stream the remote program closes itself, or bound it with something like head -n 1.

Interactive TTY#

nexusctl sandbox exec nightly-refactor --project production -t -- top

-t allocates a TTY: raw mode locally, a PTY remotely, and terminal resizes forwarded as the window changes. It implies -i.

Open a shell#

nexusctl sandbox shell nightly-refactor --project production

This is sugar for sandbox exec <slug> -it -- bash. Pass --shell sh when the image has no bash; the binary has to exist on $PATH inside the image.

The project shell sandbox#

Every project has a shell sandbox the platform manages for you. It is the fastest way to run something under the project's policy without creating a sandbox of your own.

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/shell/exec \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "command": "kubectl get pods -A",
    "timeout": 60000
  }'

{ "stdout": "...", "stderr": "", "exitCode": 0 }

In the production project, run "kubectl get pods -A" in the shell
sandbox and summarise anything that is not Running.

The agent calls shell_exec. See Agent tools.

nexusctl shell exec -p production -- kubectl get pods -A

Each argument is POSIX-shell-quoted before being joined, so the remote shell sees your arguments verbatim — the same semantics as kubectl exec.

Option Default Notes
--workdir workspace root Working directory for the command.
--timeout 30000 ms Maximum 1200000 ms (20 minutes). Raise it for builds and installs.

The shell sandbox carries the project's credentials and connections, so kubectl and aws work against the systems the project is allowed to reach — without those credentials ever being readable inside it.

List and stop active shell sessions:

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/projects/$PROJECT_ID/shell-sessions

sandbox exec has no agent equivalent

Interactive exec into an agent sandbox is a WebSocket, and there is no MCP tool for it. An agent can reach the project shell sandbox with shell_exec, but not a terminal inside another sandbox.

Over MCP#

An AI tool connected to the platform's MCP endpoint gets the same shell sandbox as a set of tools — shell_exec, shell_read_file, shell_write_file, shell_edit_file, and a spawn/stdin/stdout/kill set for long-running processes. See Agent tools.

Everything is audited#

exec, shell, and every shell-sandbox tool call is written to the audit trail with the actor, the project, the command, the result, and the duration. That applies whether the caller was a person at a terminal, an API token in CI, or an agent over MCP.