Skip to the content
security / self-hosted

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.

execution boundary

What runs where

Your computer controls the work, but your server holds the execution environment and persistent state.

Read the execution boundaries

  • 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.
network exposure

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.

Read the networking guide

  1. One SSH connection, directly on port 2222 over Tailscale or your own network.
  2. Or through an optional edge that both sides dial out to, so the server opens no port for that path.
  3. A tailnet device reaches the server over HTTPS only when web-port is set.
optional / edge

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.

Edge connection details

dashboard listeners

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.

    Local gateway details

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

    Server dashboard details

optional edge / metadata

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.

Privacy policy and retention

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

    Read the encryption boundary

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

    How the edge works

isolation limits

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.

Isolation and permission tiers

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.

    Docker inside a session

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

    Reviewing a session

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

    Standard and Enhanced sessions

  • 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

    Read what each surface protects

the session's browser

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.

Read the FAQSee it in the app

  1. The agent drives the session's own Chromium.
  2. Open the Browser tab and you see the same page.
  3. It clicks through the app it started, as a user would.
browser companion

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.

Browser isolation

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.

    The companion's policy

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

    How the browser is driven

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

    Who may open the browser

credentials / server-side login

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.

Member home and login details

  1. Login state persists in your member home.
  2. It is mounted into every session you launch. An Isolated session gets a throwaway copy.
  3. And into no one else's containers, unless you share your agent account.
credential boundaries

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.

    Token and signing-key risks

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

    Read the import policy

outbound services and reporting

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.

    Review agent network access

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

    Quota access policy

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

    Release signing

open source / gpl-3.0

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 the license notices

GPL-3.0

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 source on GitHub

next

Read the full security model

The security guide in the docs describes each of these boundaries in full.

Read the security modelInstall