Skip to main content

​
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

BackendUse caseSecurity
Local (default)Development, trusted tasksRuns on your machine — full access
DockerSecurity, reproducibilityIsolated container — agent can’t touch your host
SSHSandboxing — keeps agent away from its own codeRemote machine — agent works on a server
SingularityHPC cluster computing, rootlessApptainer/Singularity container — for HPC environments
ModalServerless cloud execution, scaleCloud sandbox — hibernates when idle, costs nearly nothing
DaytonaPersistent remote dev environmentsRemote dev environment — persistent across sessions

​
Configuration

Set the backend in Settings → Headmaster’s Library → Advanced → Terminal or directly in the config file: 
# 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. 
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

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

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. 
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. 
apptainer build ~/python.sif docker://python:3.11-slim

terminal:
  backend: singularity
  singularity_image: ~/python.sif
When to use: You’re on an HPC cluster that uses Apptainer/Singularity instead of Docker.
Commands run in a serverless cloud sandbox. The sandbox hibernates when idle, costing nearly nothing. 
uv pip install modal
modal setup

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. 
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 situationRecommended backend
Local development, trust the agentLocal
Want isolation, have DockerDocker
Want isolation, no DockerSSH
On an HPC clusterSingularity
Want cloud execution, pay per useModal
Want persistent remote dev envDaytona

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