Runtime
Environments
Environments give Swarm agents reproducible containerized environments for builds, testing, and service execution without polluting your host machine. Manage connections, configure container images, and lease on-demand testbenches.
Overview
Isolated execution where your tests and builds belong.
When building complex applications, agents frequently need to run compilers, execute end-to-end test suites, or verify services against real dependencies. Running these directly on your host machine risks version conflicts, dependency pollution, and security exposure.
Swarm solves this through Environments: declarative, reusable container specifications connected to execution hosts (local Docker or remote SSH machines). Agents can automatically lease an environment, mount or sync the current workspace, execute commands, verify results, and cleanly release the environment when finished.
Architecture
Declarative environment definitions.
An environment definition is static and contains no ephemeral runtime state. It defines how a container should be created and how your code should be made available inside it:
container image
Any standard container image (such as golang:1.24, node:22, or ubuntu:24.04) with custom environment variables, working directories, and setup commands.
provisioning strategy
Controls how workspace files enter the container: local_mount for zero-copy direct bind mounts, sync for isolated mirroring, or git_checkout for clean branch clones.
resource bounds
Explicit limits on CPU cores, memory allocation, and optional GPU requirements.
environment roles
Designated roles such as testing (default testbench), development, or build so agents know which environment fits their current task.
Connections
Run locally with Docker or remotely over SSH.
Environments run on configured execution host connections. Swarm supports two primary connection kinds:
local_docker
Connects directly to the local Docker or Podman daemon socket (such as /var/run/docker.sock). Containers run locally with fast bind-mount performance.
ssh
Connects to a remote host or build server over SSH using private key identity files. Enables offloading heavy compilation and parallel test runs to remote servers or private cloud VPS instances.
Deployments & leases
Lease-based runtime lifecycle.
Environments are not kept running indefinitely when idle. Instead, Swarm manages them through a lease-based deployment cycle:
An agent acquires a lease on the workspace's default test environment or a specified container image.
Commands, test suites, and diagnostic checks run inside the container via isolated exec actions.
When tests finish, the lease is released. The container is stopped, restarted, or recycled according to deployment policy.
Safety & boundaries
Safe isolation without secret leakage.
Swarm enforces strict boundaries between the agent runtime and execution containers:
- No credential passthrough: Host SSH keys and secrets are never copied into the container unless explicitly mapped as environment variables.
- Bounded timeouts: All container exec commands carry mandatory execution timeouts to prevent hanging processes from consuming host resources.
- Automatic cleanup: Leases carry time-to-live bounds (TTL) so abandoned sessions do not leave orphaned containers running indefinitely.