> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Code execution

> Run Linux commands with code execution through the guest transport, then inspect output and exit codes.

Use `bead exec` for code execution on an existing Linux machine. Commands use `/bin/sh -c` and start in `/root` unless you set `--cwd`.

## Run shell commands in a cloud VM

Replace `ID` with your machine ID:

```bash theme={null}
bead exec ID 'uname -a'
bead exec ID 'mkdir -p /root/project'
bead exec ID 'pwd && ls -la' --cwd /root/project
```

The working directory must exist. Shell quoting happens first on your computer, then in the guest. Single quotes keep guest variables such as `$HOME` from expanding locally.

## Capture exit codes from remote commands

```bash theme={null}
bead --json exec ID 'printf "hello\n"; exit 7'
```

JSON output includes `exit_code`, stdout, and stderr. A nonzero exit code means the command failed even when the transport succeeded. Plain CLI output prints complete stdout and stderr. The CLI exits 0 for remote success and 1 for a nonzero remote exit; use JSON `exit_code` to read the remote status, or `bead run` to preserve it as the local exit status.

The CLI exec transport sets a 25-second execution deadline. Use [bead run](https://docs.bead.run/run-work/run.md) for a bounded build with a longer command timeout, or [runner turns](https://docs.bead.run/agents/runners.md) for coding-agent work.

## Use MCP

The hosted `bead:sandbox_exec` tool uses the same guest transport. Inspect its `exit_code` and retained output fields. Read [output and recovery](https://docs.bead.run/run-work/output.md) before retrying after an uncertain response.

## Next

[Transfer files](https://docs.bead.run/connect/files.md), [forward an application port](https://docs.bead.run/connect/ports.md), or [pause the machine](https://docs.bead.run/snapshots/pause-resume.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.