Managing Swarm
Add Swarm
Add Swarm connects another runtime to your Swarm setup. Start from Desktop today; local containers are the first supported path, and managed hosting is available now through Tailscale.
Tip: Local containers and managed hosts require a workspace.
Desktop control surface
Manage Swarm from Desktop.
Open Swarm management with /swarm in Desktop, or click the Swarm button in the sidebar. Use this screen to add and link local containers.
Show the Desktop sidebar, expand the swarms row, and click Add / manage swarms.
First path
Local container.
Local containers run with Docker or Podman. They give workspace work a separate Swarm runtime while keeping setup close to your machine.
This is useful isolation, but it is not a perfect security boundary. Swarm starts a normal local container runtime, mounts the workspace paths you select, publishes the child Swarm ports back to localhost, and links the child runtime to the parent Swarm. Treat it as a convenient contained runtime, not as a hardened sandbox.
Swarm also syncs selected settings to the Swarm instance inside each container in your Swarm, as well as any linked managed hosting.
Local container setup.
Create a local container target, sync a workspace into it, then switch your active Swarm target.
Click Add Container
Start from the Add Swarm screen and choose the local container path.
Name your container
Use a clear target name, like dev-container. This name appears later in chat and terminal target switching.
Choose Docker or Podman
Pick the container runtime installed on your machine.
Choose the workspace to sync
Select the workspace Swarm should mount or bootstrap into the container runtime. Mounted workspace files remain reachable by processes inside the container.
Add packages if needed
Add extra packages your project needs inside the container.
Bypass permissions inside the container only
Keep host permissions enabled while allowing agents inside the isolated container to run without permission prompts.
Switch to the container target
In chat, use the target dropdown and choose the container name. In terminal, press Alt + S to swap Swarm targets.
Show the local container path from the Add Swarm screen and where the new runtime appears afterward.
Current behavior
What Swarm creates for a local container.
runtimeSwarm uses the local container runtime available on the host. It checks Podman and Docker, then starts the selected runtime with a normal run -d container.imageProduction Swarm pulls and verifies the official release image from ghcr.io/swarm-agent/swarm. Development builds use the local localhost/swarm-container-mvp:latest image; optional package additions build a derived image only in dev mode.portsThe child backend listens on 0.0.0.0:7781 inside the container so it can accept traffic on the container network interface, and the child Desktop surface listens on 5555. That internal 0.0.0.0 bind is not the same as exposing the service on every network interface of your host. Swarm publishes both services back to the host on localhost-only ports by default: 127.0.0.1:<host port> for the backend and 127.0.0.1:<host port + 1> for Desktop.networkWhen a group network is selected, Swarm creates or reuses a runtime network. Docker gets host.docker.internal:host-gateway; Podman gets a disabled-DNS network plus a host.containers.internal gateway alias.mountsThe workspace mount paths are verified against the account-owned workspace path, then passed to Docker or Podman with -v source:target. Swarm does not make those mounts read-only today, so changes inside the container change the mounted host files too.userSwarm runs the container command as 0:0 and passes the host UID/GID through SWARM_RUNTIME_UID and SWARM_RUNTIME_GID. With Podman, Swarm also adds --userns=keep-id.bootstrapThe child gets a generated startup config through SWARM_CHILD_STARTUP_CONFIG, runs offline-first, advertises itself back to the parent, and can optionally start with container-only permission bypass.Bottom line: the work happens inside a container, but the container is intentionally integrated with the parent Swarm. It has the workspace mounts, local host port mappings, runtime networking, and bootstrap material needed to act as another Swarm target.
Security guidance
For maximum isolation, bring your own hardened container or VM.
The built-in Add Container flow optimizes for a fast extra Swarm target, not for the strongest possible sandbox. It does not currently expose every Docker or Podman hardening choice, and it still depends on the security properties of your local container runtime, the host user’s runtime permissions, and the mounts you selected.
The selected workspace paths are still mounted from your host. If you run the child container with bypass permissions and an agent deletes files under a mounted workspace path, those host files are deleted too. Built-in local containers are useful for personal project isolation and convenience; they are not a guarantee that your important files are protected somewhere else.
If you need the maximum security possible, build a container, VM, or remote Linux environment to your own policy first. Decide the base image, user namespace, filesystem mounts, network egress, secrets, package set, and runtime flags yourself. Then install and run Swarm inside that environment and navigate it from Desktop when useful.
use built-in containers forConvenient project isolation, separate agent runs, trying dependencies away from the host runtime, and keeping host permission prompts stricter while the container can be more permissive.use your own hardened environment forUntrusted repositories, high-risk code execution, strict network isolation, read-only mounts, no host runtime socket exposure, custom seccomp/AppArmor policy, or compliance-controlled workloads.recommended patternCreate the hardened environment yourself, install Swarm inside it, expose only the access path you accept, then use Desktop to operate that Swarm target.Second path
Managed host.
Managed hosting links another machine as a Swarm runtime. Use it when work should move off the local machine or stay available longer than a local container session.
The host Swarm you are on is not where you start the process. Download Swarm on the machine you want to link, make sure that machine is on Tailscale, and request to link it to the main machine. Both machines must be on Tailscale and logged in so they can reach each other.
There are two supported ways to start: use the Add Swarm page from Desktop, or use the onboarding flow on the machine you want to link. In both cases, start from the machine being added, then request to link back to the main Swarm.
We understand this is a limitation. For now, Tailscale is the best managed-hosting option for a multi-server Swarm setup because it gives Swarm a secure private network without requiring users to manage SSH tunnels or WireGuard configuration after the fact. Tailscale also has a generous free tier and is the product we can recommend for users who want Swarm to tunnel back safely and just work.
Show the managed host path from Add Swarm and how Desktop confirms the linked host is available.