Know the boundaries.
Your server runs the agents. A sandbox contains the work. Neither makes an agent harmless: what you mount, connect and authorize determines what it can reach.
What runs where
Your computer controls the work, but your server holds the execution environment and persistent state.
Your computer
The CLI and local dashboard control your local checkout. Dashboard requests reach your server over SSH.
Your server
Repositories, session records and member homes live on the machine you or your team operate. It opens terminals only inside sandboxes, never on the host.
Docker containers
The agent and tools run unprivileged with the session checkout and the launcher's member home mounted, using the credentials and network they can reach. The session's browser has a container of its own. With session-runtime vm the sandbox is a virtual machine instead.
External providers
The agent talks to its model provider. Authorized tools reach services such as GitHub using your account.
- The member home is mounted, never copied, into the Docker container, beside the session checkout.
- There the agent and its tools run unprivileged, as uid 1000, and make requests out to model providers, GitHub with your token, and package installs.
- Beside it, the session's browser companion runs a headless Chromium in a container of its own, which mounts no checkout, member home, logins or Docker socket.
Choose your connection path
SSH defaults to port 2222, carrying control, Git, events, terminals and dashboard forwarding over one connection. You choose how to make it reachable; Tailscale is recommended.
- One SSH connection, directly on port 2222 over Tailscale or your own network.
- Or through an optional edge that both sides dial out to, so the server opens no port for that path.
- A tailnet device reaches the server over HTTPS only when web-port is set.
Relay without inbound ports
Without direct reachability, client and server can both dial out to an edge. GitHub sign-in enables relayed SSH without Tailscale or an inbound server port for that path. Server setup turns the project's edge on when the host has no tailscaled, and prints what the edge sees and how to turn it off.
No HTTP unless you set web-port
The server opens no HTTP port unless you set web-port, and that one listens on the host's tailnet addresses only.
- local gui
Loopback on your computer
The local GUI binds 127.0.0.1 and nothing else, on your own computer. Every request needs its per-process bearer token, loopback included, and it reaches your server over SSH. It adds no dashboard listener to your server.
- optional / web-port
HTTPS on your tailnet
The web-port setting is off by default; enabling it serves the dashboard over HTTPS on the server's tailnet addresses. Tailscale identifies each request, independently of the local GUI.
What the relay sees
The publisher-operated edge stores account identity, device, claimed-server and server-directory records when you use it. While relaying, it sees your IP address, destination server, connection timing and byte counts.
- end-to-end encryption
Session content stays encrypted
Terminal, agent, file and dashboard session content travels inside SSH, encrypted end to end between your computer and server, so the edge cannot read it. Encryption does not hide connection metadata from the relay. A ChatGPT or Claude connector is the exception: its TLS ends at the edge.
- hosting status
Hosting is not launched
There is no hosted Cloudfield server. The protocol reserves a kind for one, and nothing produces it. The optional edge exists today, but your workspace still runs on your own server.
Unprivileged agent, root by tier
Agents run unprivileged, as uid 1000, in every permission tier. Root access runs sudo without asking, Default asks the session's owner or a workspace admin before each sudo, and Isolated refuses it. The container keeps Docker's default capabilities, with no second boundary inside it and no forced read-only root filesystem. Treat root in a session as able to read or change anything its sandbox can reach, and review mounts, network access and credential scopes.
The server opens terminals only inside sandboxes, never on the host, and never gives a session the host's Docker socket. Containers share the host's kernel; with session-runtime vm each session runs in a virtual machine with its own kernel.
- docker inside sessions / sysbox
A daemon of its own, or none
With Sysbox installed, each session except an Isolated one starts its own Docker daemon, and root in the container maps to an unprivileged user on the host. The container is not privileged and never gets the host's Docker socket. Docker inside a Default session lets the agent reach root in its container without asking. Without Sysbox a session has no daemon and no socket.
- review before merge
Nothing lands on its own
Every session works on its own branch and ends there. Cloudfield never switches your branches or merges a session into your base branch: you read the diff, then push it and open a pull request, or pull it into your clone. Publishing never force-pushes.
- permission prompts
Agents do not stop to ask
By default an agent runs with its own permission prompts off, in every mode. In an Enhanced session of Claude Code, Codex or Gemini you can switch to a mode that asks. The sandbox is the boundary, not a prompt; only sudo in a Default session waits for a person.
- operator responsibility
The host is trusted
The sandbox does not protect workspace data from server administrators, and a separate session checkout does not make its mounted member home private. Homes and backups carry credentials: restrict access and encrypt backups. What lives in the data directory
Agents test the app they build, in a browser you can watch
Every session can open its own Chromium on the server, driven by Playwright, in a container next to the session's, so localhost is the app the agent just started. Open the session's Browser tab and you see what the agent sees.
- The agent drives the session's own Chromium.
- Open the Browser tab and you see the same page.
- It clicks through the app it started, as a user would.
A browser kept apart from your files
Each session can open a headless Chromium that its agent drives and your team can watch. On a Docker server it runs in a companion container of its own, joined to the session's network so it reaches the app the agent started, and to nothing else of the session. With session-runtime vm it runs inside the session's virtual machine, which is no boundary against root in that machine.
It shares the session's network reach, and a page can hold cookies or customer data: use test accounts, not production logins.
- hardened container
No checkout, home or credentials
The container runs as UID 1000 with a read-only root filesystem, every capability dropped and no-new-privileges, and Chromium keeps its own sandbox. Its only mount is a private control directory: never the checkout, a member home, signing keys, agent logins or the Docker socket.
- no debugging port
Commands over a pipe
Playwright drives Chromium through a debugging pipe, not a CDP port. The server passes typed commands and frames over a Unix socket, and no client gets raw CDP access.
- steer required
Viewers cannot watch it
Watching or driving a session's browser needs Steer, the permission to message that session, because the page may be signed in to something. Permission to view the session is not enough.
Sign in on your server
Complete the provider's native login in your server-side environment terminal. Login state persists in your member home, mounted read-write into that terminal and every session you launch (an Isolated session gets a throwaway copy, with the agent's login still mounted), and into no one else's containers, unless you share your agent account, which lends only that agent's login.
- Login state persists in your member home.
- It is mounted into every session you launch. An Isolated session gets a throwaway copy.
- And into no one else's containers, unless you share your agent account.
Credential boundaries
Cloudfield does not copy vendor credentials to clients or synchronize them.
- github credentials
Plaintext tokens need care
Connecting GitHub stores a plaintext gh token in the member home. Root in any of your sessions can read or replace it; the token's scopes define its reach. The private signing key stays on the server, outside the home: sessions sign through an agent and cannot copy it.
- configuration import
Scanned before and after upload
Configuration import is separate from login: known credential names are left out, the CLI runs the server's secret scanner before sending and never sends a flagged file, and the server scans every file again. The scanner finds known patterns, not every secret, so do not assume an arbitrary secret stays on your computer.
What leaves the server
- model + service apis
Self-hosted does not mean offline
Agents send requests to their model providers. Connected tools and package installers make their own service requests.
- subscription quota reporting
Usage checks run server-side
Quota reporting reads Claude or Codex login state from the member home and sends bearer tokens to fixed vendor HTTPS usage endpoints. Those tokens are not sent to the browser.
- releases + container images
Updates are signed
Release checks ask GitHub for the newest release, and updates download its assets. Every updater checks them against the release's signed manifest before installing anything. Missing published container images can be pulled from GHCR.
Inspect the source yourself
Cloudfield is licensed under GNU GPL version 3; bundled dependencies retain their own licenses. These references describe release v0.9.0-nightly.1.
Read every line of it.
Cloudfield is open source under GPL-3.0, so you can read every line of code and run it on your own servers.
Read the full security model
The security guide in the docs describes each of these boundaries in full.