Install the native package
Install Agent Fleet on a single-user Linux host without Docker (WSL2 included) and start using it from the browser. It runs without installing anything on the host: there is no need for tmux, git, node or the agent CLIs there.
How it works
Section titled “How it works”| What you do | What happens |
|---|---|
| Run the installer, or extract the tar | The af command is available |
Run af start |
The first time only, it fetches, verifies and extracts the rootfs (~200 MB). The Control Plane and the Console run as host processes |
Open http://localhost:8099 in a browser |
The Console opens with no sign-in. Workspaces run in a bubblewrap sandbox |
| Start a workspace for the first time | The agent CLIs are installed, at their pinned versions, into the virtual HOME |
For several people, or for container isolation and CPU / memory limits, choose a Docker-based target (Deploy with Docker Compose and others).
Before you start
Section titled “Before you start”| What you need | Notes |
|---|---|
| A Linux kernel (unprivileged user namespaces) | The stock WSL2 kernel has AppArmor disabled, so it should work as is. Ubuntu 23.10 and later may need the setting below |
| bash, coreutils, tar | Standard userland only. zstd is bundled as bin/zstd, so the host does not need it |
| curl or wget | Used only for the first rootfs download (see also Carry it in by hand) |
(For agy) a CPU that exposes RDRAND |
agy’s (the Antigravity CLI’s) FIPS build aborts without RDRAND. Where the kernel has withdrawn the instruction, the Agent masks it out of OpenSSL’s detection and runs agy anyway, its randomness coming from the kernel. AF_AGY_RDRAND_MASK=0 refuses that, and the Console hides agy |
On a kernel with user namespaces disabled entirely, the native package cannot run: use the Docker target (agent-fleet-<v>.tar.gz).
There is no native package for macOS. On an Apple Silicon Mac, run it inside a Linux VM (Run on an Apple Silicon Mac).
When AppArmor blocks it on Ubuntu 23.10 or later
Section titled “When AppArmor blocks it on Ubuntu 23.10 or later”On bare-metal Ubuntu 23.10 or later (not WSL), AppArmor may restrict unprivileged user namespaces. In that case, run once:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0# make it permanent:echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-agent-fleet.conf1. Install it
Section titled “1. Install it”The installer from the distribution repo (k-k1/agent-fleet-dist) extracts to ~/.local/opt/agent-fleet/<v>/ and symlinks ~/.local/bin/af.
curl -fsSL https://raw.githubusercontent.com/k-k1/agent-fleet-dist/main/install.sh | bashaf start # first run only: fetch, verify, and extract the rootfs (~200MB)# open http://localhost:8099 in a browser| Environment variable | Meaning |
|---|---|
AF_VERSION |
The version to install. The default is the latest release |
AF_PREFIX |
The install prefix. The default is ~/.local |
AF_NO_AUTOUPDATE |
1 skips enabling the daily update timer (Update the native package) |
If you received the tar directly, extract it and use the af inside. <arch> is amd64 or arm64, matching uname -m’s x86_64 / aarch64.
tar xzf agent-fleet-native-<v>-linux-<arch>.tar.gzcd agent-fleet-native-<v>-linux-<arch>./af start # first run only: fetch, verify, and extract the rootfs (~200MB)# open http://localhost:8099 in a browser2. Start it and open it
Section titled “2. Start it and open it”- The first
af startdownloads the rootfs pinned inrootfs.json(URL and sha256). Later starts work offline (the extracted rootfs is reused) af startruns in the foreground; stop it with Ctrl-C. To run it as a service, see Run it as a systemd service- Open
http://localhost:8099in a browser. On WSL2 a browser on the Windows side opens it directly af statusshows whether the Control Plane and the workspaces are running
There is no sign-in screen. It runs as one fixed AUTH=dev user, and that user is a deployment administrator (super_admin).
The tenant settings screen is reachable straight after af start.
The agent CLIs
Section titled “The agent CLIs”The agent CLIs are not in the package.
| CLI | When it is installed |
|---|---|
| claude, codex, opencode, cursor, copilot, agy, rtk | On a workspace’s first start, the versions pinned in versions.json go into the virtual HOME. Only this step needs the network |
| kiro (~855 MB) | The first time a Kiro session starts |
| Muse Code | Not until you ask for it: the “Install Muse Code” button on its card in ⚙Settings → Agents fetches the pinned version into your home |
Data locations
Section titled “Data locations”| Contents | Location |
|---|---|
| All data (DB, workspace homes, claude-config, extracted rootfs) | ~/.local/share/agent-fleet. Override with WS_DATA |
| The package itself | The extracted directory. It holds no data, so it is safe to delete |
- The layout is compatible with the Docker targets, so the same
WS_DATAcan move between docker and native - From Windows Explorer it is at
\\wsl.localhost\<distro>\home\<user>\.local\share\agent-fleet
Connect repositories through OAuth
Section titled “Connect repositories through OAuth”To clone and push private repositories, connect GitHub or Bitbucket under Settings → Git hosting in the Console. Pasting a token works with no configuration at all.
To also enable the one-click “Connect via OAuth”, register the OAuth app in the Console’s tenant settings (Choose the OAuth apps for integrations). There is no environment variable for it.
| Provider | What to enter | Setup |
|---|---|---|
| GitHub (device flow) | client_id only |
Create an OAuth App under GitHub → Settings → Developer settings → OAuth Apps with Enable Device Flow ON. The client_id is not a secret. Device flow needs no callback URL, so it works as is on localhost |
| Bitbucket (authorization code) | Key and Secret | Create an OAuth consumer whose Callback URL exactly equals <PUBLIC_BASE_URL>/api/oauth/bitbucket/callback. Set PUBLIC_BASE_URL to how you reach the Console (e.g. http://localhost:8099). The screen shows the URL to paste |
For a single-user native install, GitHub’s device flow is the easiest, since it needs no callback.
Differences from the Docker targets
Section titled “Differences from the Docker targets”| Difference | What it means |
|---|---|
| One user only | Fixed to AUTH=dev. There is no container isolation: every workspace runs in a bubblewrap sandbox under the same OS user |
| No memory limits | No cgroups are used, so WS_MEMORY has no effect. A heavy build can take down the whole host |
| The browser pane’s Chromium is fetched on first use | A pinned version, ~200 MB. See “When Chromium’s sandbox does not work” below |
When Chromium’s sandbox does not work
Section titled “When Chromium’s sandbox does not work”Under bubblewrap the SUID sandbox is unavailable, and on some systems Chromium’s namespace sandbox does not work either. In that case start with:
WS_ENV=AF_CHROMIUM_NO_SANDBOX=1 af start- The variable reaches the workspace through
WS_ENV(a comma-separatedKEY=VALlist). Set bare onaf start, it only reaches the Control Plane - An acceptable trade-off for the browser pane, which only connects to localhost. Do not use it to browse untrusted sites
Sharing Go build-cache entries between worktrees
Section titled “Sharing Go build-cache entries between worktrees”The workspace image sets GOFLAGS=-trimpath so worktrees at different paths share ~/.cache/go-build entries instead of each adding its own copy. Whether a native workspace gets it depends on how the Control Plane launches workspaces:
- With a rootfs (
AF_NATIVE_ROOTFS;af startalways uses one): sessions start from the image’s own environment. The setting arrives once you update to a release whose rootfs includes it, restart the Control Plane, and stop and start any running workspace. To turn it on before that, pass it throughWS_ENV - Without one (for example
deploy/local/run-dev.sh native, which uses the host’sworkspace-agentand Go): the image’s environment is not used and the workspace’s environment is built from scratch, so aGOFLAGSexported in the shell that starts the Control Plane does not reach sessions. Pass it throughWS_ENV
WS_ENV=GOFLAGS=-trimpath af start # with a rootfs: before updating, or to overrideWS_ENV=GOFLAGS=-trimpath deploy/local/run-dev.sh native # without a rootfsIn either mode WS_ENV takes precedence (with a rootfs it overrides the image’s value). Entries already in ~/.cache/go-build were built without -trimpath, so new builds do not share them; they stay until Go trims them (5 days unused). Builds you run directly in a host shell are not affected by any of this and use the host’s own ~/.cache/go-build, separate from the workspace’s: export GOFLAGS=-trimpath there if you want the host’s worktrees to share entries.
What you can add
Section titled “What you can add”| What you want | Page |
|---|---|
| Read replies aloud (VOICEVOX) | Run the read-aloud engine |
| Generate images on a ComfyUI on your network | Generate images on your own ComfyUI |
| Borrow the inference engines of an Agent Fleet on AWS | Borrow another deployment’s engines |
| Chat on a llama.cpp on your LAN | Chat on a llama.cpp on your LAN |
Each of them is an environment variable on af start, or an Environment= line in the systemd unit. af passes your shell environment through to the Control Plane.
When it goes wrong
Section titled “When it goes wrong”| Symptom | Where to look |
|---|---|
af start stops on a user-namespace error |
On Ubuntu 23.10 or later, the AppArmor setting. If the kernel disables them, use a Docker target |
| The browser pane’s Chromium does not start | When Chromium’s sandbox does not work |
| Port 8099 is in use | Another af start, or the systemd service, is already running |
Related
Section titled “Related”For agents
Send this prompt to your agent to read this page.
Read https://agent-fleet.org/docs/operate/native/install/index.md