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	Remote sandboxing	Remote machine — agent works on a server
Singularity	HPC cluster computing	Apptainer/Singularity container — rootless
Modal	Serverless cloud execution	Cloud sandbox — hibernates when idle
Daytona	Persistent remote dev environments	Remote dev environment — persistent across sessions

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

Configuration

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

terminal:
  backend: local    # or: docker, ssh, singularity, modal, daytona
  cwd: "."
  timeout: 180      # Command timeout in seconds

Backend details

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.

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

terminal:
  backend: docker
  docker_image: python:3.11-slim

Container behavior:

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.
Container is stopped and removed on shutdown.

Container persistence:

terminal:
  backend: docker
  container_persistent: true    # Persist /workspace and /root across restarts

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)

Security hardening:

Read-only root filesystem
All Linux capabilities dropped
No privilege escalation
PID limits (256 processes)
Full namespace isolation
Persistent workspace via volumes

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: When your project lives on a remote server, or when you want the agent away from your local files.

SSH is the recommended backend for running the agent in Hands-Off or Autopilot mode — it prevents the agent from accidentally modifying your local system.

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

# Build the image first
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.

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 without managing the infrastructure yourself.

Terminal tool behavior

Regardless of backend:

Behavior	Details
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). You get a session ID to poll, wait, or kill 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.

Security

Container isolation details and security model overview.

Tools & Toolsets

Enabling/disabling the terminal tool per specialist.

Getting Started

Core Concepts

HeadmasterUI Settings

Runtime Settings

Features

Security & Privacy

Maintenance

Reference

Terminal Backends

Terminal Backends

Available backends

Choosing a backend

Configuration

Backend details

Terminal tool behavior

Security

Tools & Toolsets

​Terminal Backends

​Available backends

​Choosing a backend

​Configuration

​Backend details

​Terminal tool behavior

Security

Tools & Toolsets

Terminal Backends

Available backends

Choosing a backend

Configuration

Backend details

Terminal tool behavior