Shell

The bash tool is how the agent runs commands on the computer. Each call executes bash -c <command> in a non-login shell, so a cwd you pass is honored as the working directory for that command. It is a single request/response — not a stream.

Exec on a sleeping computer wakes it automatically. Exec on a parked computer is rejected — resume it first. See lifecycle.

Examples

vetta computer exec box -- "ls -la /workspace"

# with a timeout; cd inside the command, there is no --cwd
vetta computer exec box --command "cd /workspace && npm test" --timeout-ms 30000

const result = await vetta.computers.exec(computer.id, {
  command: "npm test",
  cwd: "/workspace",
  env: { CI: "1" },        // this call only; not persisted
  timeoutMs: 30_000,
});

console.log(result.exitCode, result.stdout);

curl https://api.vetta.sh/v1/computers/$COMPUTER_ID/exec \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm test",
    "cwd": "/workspace",
    "env": { "CI": "1" },
    "timeout_ms": 30000
  }'

Output caps at a glance

Field	Cap	Behavior beyond cap
`stdout`	262,144 chars	Truncated
`stderr`	262,144 chars	Truncated

When you expect large output, redirect it to a file (… > /workspace/out.log 2>&1) and read the parts you need with the filesystem tools instead of returning it all through stdout.

Fields

string

required

The command line to run. Executed as bash -c <command>.

string

Working directory for this command. Because the shell is non-login, cwd is respected for the call.

object

Environment variables for this call only. They are not persisted — the next bash call starts without them. There is no create-time environment injection.

integer

Maximum time to wait before the command is killed and the call returns.

env is per-call and ephemeral. There is no way to bake environment variables into a computer at create time. With the coming egress pinning, secrets are supplied by the vault at the network boundary rather than as sandbox env vars — see Networking.

Response

The command is run to completion and its output is buffered, then returned together:

string

Buffered standard output. Capped at 262,144 characters; output beyond the cap is truncated.

string

Buffered standard error, capped at 262,144 characters independently of stdout.

integer

The process exit code.

The bash tool is not streaming. stdout and stderr are collected in full (up to the cap) and returned once the command exits or timeout_ms elapses. For long-running work, have the command write progress to a file and poll it with read.

Next: browser

Drive a real, managed browser scoped to an allow-list of domains.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Examples

Output caps at a glance

Fields

Response

Next: browser

​Examples

​Output caps at a glance

​Fields

​Response

Next: browser

Examples

Output caps at a glance

Fields

Response