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

# Exec

> Run commands inside a running machine.

Exec runs a command inside an existing machine and returns stdout, stderr, exit
code, and process metadata. Use shell mode for authored command strings and
argv mode when exact argument boundaries matter.

## What state changes

* The machine process table changes while the command is running.
* Files, environment-visible side effects, and services created by the command
  remain in that machine until changed or destroyed.
* Background commands continue after the API call returns.

## Usage

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

  with Machine.create() as machine:
      result = machine.commands.run("echo hello > /workspace/out.txt", shell=True)
      print(result.exit_code)
      print(machine.files.read("/workspace/out.txt").strip())
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine exec mch_123 --shell "echo hello > /workspace/out.txt"
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -fsS -X POST \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"command":"echo hello","shell":true,"timeout_secs":30}' \
    "${NULLSPACE_API_URL}/v1/machines/${MACHINE_ID}/exec"
  ```
</CodeGroup>

The raw API accepts `command`, optional `args`, `timeout_secs`, `cwd`, `envs`,
`shell`, and `background`. Use `shell: true` for a shell string. Leave
`shell` false and pass `args` when you need exact argv boundaries.

API reference: [execCommand](../api-reference) (`POST /v1/machines/{id}/exec`).

Guide: [Commands and processes](../guides/python-sdk/commands-processes).
Example: [Examples](../examples).