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

# Terminal backends

> - **Timeout:** Commands time out after the configured timeout (default 180 seconds). Long-running commands can use backg

# Terminal backends

The terminal tool lets the agent execute shell commands on your machine — or on a remote machine, or inside a container. Headmaster supports 6 terminal backends, each for a different use case.

***

## Available backends

| Backend             | Use case                                        | Security                                                   |
| ------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
| **Local** (default) | Development, trusted tasks                      | Runs on your machine — full access                         |
| **Docker**          | Security, reproducibility                       | Isolated container — agent can't touch your host           |
| **SSH**             | Sandboxing — keeps agent away from its own code | Remote machine — agent works on a server                   |
| **Singularity**     | HPC cluster computing, rootless                 | Apptainer/Singularity container — for HPC environments     |
| **Modal**           | Serverless cloud execution, scale               | Cloud sandbox — hibernates when idle, costs nearly nothing |
| **Daytona**         | Persistent remote dev environments              | Remote dev environment — persistent across sessions        |

***

## Configuration

Set the backend in **Settings → Headmaster's Library → Advanced → Terminal** or directly in the config file:

```yaml theme={null}
# In the runtime config
terminal:
  backend: local    # or: docker, ssh, singularity, modal, daytona
  cwd: "."          # Working directory
  timeout: 180      # Command timeout in seconds
```

***

## Local backend

The default. Commands run directly on your machine in the working directory. Full access to your file system, installed tools, and environment.

**When to use:** Development, trusted tasks, when you want the agent to have full access to your project.

**Security:** The agent can run any command you can. In Work Along mode, every command requires your approval. In Hands-Off mode, the agent runs commands without asking.

***

## Docker backend

Commands run inside a Docker container. The agent can't touch your host file system — only the container's file system.

```yaml theme={null}
terminal:
  backend: docker
  docker_image: python:3.11-slim
```

### Under the hood

* One persistent container, shared across the whole process.
* Headmaster starts a single long-lived container on first use and routes every terminal, file, and `execute_code` call through `docker exec` into that same container.
* Working-directory changes, installed packages, env tweaks, and files in `/workspace` carry over between tool calls.
* Persists across new conversations and subagent delegations.
* Container is stopped and removed on shutdown.
* Behaves like a persistent sandbox VM, not a fresh container per command.

### Container persistence

```yaml theme={null}
terminal:
  backend: docker
  container_persistent: true    # Persist /workspace and /root across restarts (default: true)
```

With `container_persistent: true`, files in `/workspace` and `/root` survive Headmaster restarts. With `false`, the container starts fresh each time.

### Container resources

```yaml theme={null}
terminal:
  backend: docker
  container_cpu: 1              # CPU cores (default: 1)
  container_memory: 5120        # Memory in MB (default: 5GB)
  container_disk: 51200         # Disk in MB (default: 50GB)
```

### Container security

All container backends run with security hardening:

* Read-only root filesystem (Docker).
* All Linux capabilities dropped.
* No privilege escalation.
* PID limits (256 processes).
* Full namespace isolation.
* Persistent workspace via volumes, not writable root layer.

***

## SSH backend

Commands run on a remote machine via SSH. The agent works on a server instead of your local machine.

```yaml theme={null}
terminal:
  backend: ssh
```

Set credentials in the runtime config or environment:

```
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa
```

**When to use:** Security — the agent can't touch your local files. Or when your project lives on a remote server.

**Recommended for security:** If you're running the agent in Hands-Off or Autopilot mode, the SSH backend prevents the agent from accidentally modifying your local system.

***

## Singularity / Apptainer backend

For HPC (high-performance computing) cluster environments. Rootless — doesn't require root access.

```bash theme={null}
apptainer build ~/python.sif docker://python:3.11-slim
```

```yaml theme={null}
terminal:
  backend: singularity
  singularity_image: ~/python.sif
```

**When to use:** You're on an HPC cluster that uses Apptainer/Singularity instead of Docker.

***

## Modal backend (serverless cloud)

Commands run in a serverless cloud sandbox. The sandbox hibernates when idle, costing nearly nothing.

```bash theme={null}
uv pip install modal
modal setup
```

```yaml theme={null}
terminal:
  backend: modal
```

**When to use:** You want cloud execution without managing a server. The sandbox scales automatically and costs almost nothing when idle.

***

## Daytona backend

Persistent remote development environments. The agent works in a Daytona-managed environment that persists across sessions.

```yaml theme={null}
terminal:
  backend: daytona
```

**When to use:** You want a persistent remote dev environment that the agent can work in, without managing the infrastructure yourself.

***

## Choosing a backend

| Your situation                     | Recommended backend |
| ---------------------------------- | ------------------- |
| Local development, trust the agent | **Local**           |
| Want isolation, have Docker        | **Docker**          |
| Want isolation, no Docker          | **SSH**             |
| On an HPC cluster                  | **Singularity**     |
| Want cloud execution, pay per use  | **Modal**           |
| Want persistent remote dev env     | **Daytona**         |

***

## Terminal tool behavior

Regardless of backend, the terminal tool:

* **Timeout:** Commands time out after the configured timeout (default 180 seconds). Long-running commands can use background mode.
* **Background execution:** Set `background=true` for long-running processes (servers, watchers, builds). The process runs in the background and you get a session ID to poll, wait, or kill it later.
* **Working directory:** The agent can `cd` between directories. In container backends, the working directory persists across calls.
* **Environment variables:** Exported env vars persist across calls in the same session (for local and container backends).
* **Output capture:** stdout and stderr are captured. Output is truncated if it exceeds 50KB.