> ## 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.

# Execute Commands In Machine

> Run foreground, streaming, background, and process-management commands with the CLI.

Use `nullspace machine exec` for one-off commands and
`nullspace machine process ...` for background process management.

## Foreground Commands

Run a shell command:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 --shell "echo hello && python3 --version"
```

Run a structured command with arguments:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 python3 -- -c "print('hello')"
```

Use `--cwd`, `--env`, and `--timeout` to control execution:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 \
  --cwd /workspace \
  --env PYTHONUNBUFFERED=1 \
  --timeout 120 \
  --shell "pytest -q"
```

Do not combine `--shell` with structured argv for the same command. Shell mode
treats the command as an authored shell string; argv mode preserves argument
boundaries.

## Streaming Output

Use the process stream command when you want stdout and stderr as the command
runs:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine process stream mch_123 python3 -- -u script.py
```

`process stream` also accepts `--timeout`, `--cwd`, repeatable `--env`,
`--shell`, and `--json`:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine process stream mch_123 \
  --cwd /workspace \
  --env PYTHONUNBUFFERED=1 \
  --timeout 120 \
  --shell "python3 -u script.py"
```

Streaming uses the machine exec WebSocket channel underneath. With `--json`, the
command suppresses live printing and emits final `exit_code`, `stdout`,
`stderr`, and `pid`.

## Background Processes

Start long-running work in the background:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 \
  --shell "python3 -m http.server 8080" \
  --background
```

Then list, inspect logs, attach, send stdin, or kill by PID:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine process list mch_123
nullspace machine process logs mch_123 1234
nullspace machine process attach mch_123 1234
printf "q" | nullspace machine process stdin mch_123 1234
nullspace machine process kill mch_123 1234
```

Add `--json` to `process list`, `logs`, `stdin`, `kill`, `stream`, or `attach`
when another program needs structured output. `stdin --json` reports
`bytes_sent`; `attach --json` reports the final command result.

## Code Interpreter

For notebook-style stateful code, use the code interpreter commands instead of
plain shell exec:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine code run mch_123 "x = 41; x + 1" --json
nullspace machine code install mch_123 numpy pandas
nullspace machine code context create mch_123 --cwd /workspace
```

`machine code run-job list` is available for read-only hosted beta inspection.
`machine code run-job create`, `get`, `cancel`, and `wait` are not part of the
hosted private beta launch surface because remote host-agent routing for queued
code runs is not implemented yet.

For short one-off language snippets that should use command execution rather
than notebook state, the process namespace also exposes:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine process code-run mch_123 "print('hello')" --language python --json
```

## Exit Codes And JSON

Use `--json` on supported commands when an agent or script needs structured
results:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 --shell "python3 -m pytest -q" --json
```

If a CLI command fails, the process exits non-zero. See
[Error Codes](../error-codes) for stable error-code anchors.

## Related

* [Commands](../commands/overview)
* [Streaming Command Output](../commands/streaming)
* [Background Processes](../commands/background)
* [Code Interpreter](../code-interpreter/overview)