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

# Background Commands

> Start a command and attach to it later

`background: true` returns as soon as the process is running. The command keeps running after the call returns. Use the pid to wait, attach again, or stop it.

Do not combine `background` with a foreground stream. Attach with the pid instead.

Omit the timeout, or pass `0`, and the command has no deadline. The CLI default is 300 seconds, so pass `--timeout 0` when the command should keep running.

```python Python theme={"dark"}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create()

handle = sandbox.run_cmd(
    command="sh -lc 'echo started; sleep 2; echo finished'",
    background=True,
    timeout=0,
)
print(handle.pid)

finished = handle.wait()
print(finished.exit_code, finished.stdout)

attached = sandbox.command.connect(handle.pid)
print(attached.stdout)

server = sandbox.run_cmd(command="sleep 30", background=True, timeout=0)
server.kill()

sandbox.kill()
```

```typescript TypeScript theme={"dark"}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create();

const handle = await sandbox.runCmd("sh -lc 'echo started; sleep 2; echo finished'", {
  background: true,
  timeout: 0,
});
console.log(handle.pid);

const finished = await handle.wait();
console.log(finished.exitCode, finished.stdout);

const attached = await sandbox.command.connect(handle.pid);
console.log(attached.stdout);

const server = await sandbox.runCmd('sleep 30', { background: true });
await server.kill();

await sandbox.kill();
```

```bash CLI theme={"dark"}
# Start a command in the background — prints the command record with its pid
gravixlayer runtime exec "$RT" --background --timeout 0 -- \
  sh -lc 'echo started; sleep 2; echo finished'

# Inspect and manage tracked commands
gravixlayer runtime commands list "$RT"
gravixlayer runtime commands get "$RT" <PID>

# Re-attach to live output (scrollback first, then live)
gravixlayer runtime commands attach "$RT" <PID>

# Stop it — KILL by default; TERM/INT/HUP via --signal
gravixlayer runtime commands kill "$RT" <PID> --signal TERM
```

```bash cURL theme={"dark"}
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"sh","args":["-lc","echo started; sleep 2; echo finished"],"background":true}'
```

| Method | Path | Result |
| - | - | - |
| GET | `/v1/agents/runtime/{runtime_id}/commands` | Running and recently finished commands |
| GET | `/v1/agents/runtime/{runtime_id}/commands/{pid}` | One command |
| GET | `/v1/agents/runtime/{runtime_id}/commands/{pid}/stream` | Output until the command exits |
| DELETE | `/v1/agents/runtime/{runtime_id}/commands/{pid}?signal=TERM` | Stop the command |

`signal` may be `KILL` (the default), `TERM`, `INT`, or `HUP`. Closing the follow stream leaves the command running. A deadline ends it with exit code `124`.


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