Skip to main content

Getting Started

This guide walks you through installing Eclipse Enclave and starting your first sandboxed agent session.

info

The docs are still being filled in. The commands and paths below reflect the current CLI and will get more detail over time.

Prerequisites​

  • A supported host: Linux, macOS, or Windows through WSL2. On Windows, enclave.exe is a launcher that forwards to the Linux build inside a WSL2 distribution.
  • A container backend. Enclave uses Docker; an experimental QEMU microVM backend exists but currently runs without network restrictions, is x86-64 only, and is practical only on x86-64 Linux hosts, where KVM can accelerate it.
  • Git. Enclave runs from inside a git repository, and works with git worktrees when you want to isolate parallel sessions.
  • Credentials for a supported agent, such as Claude Code, Codex, or OpenCode.

Install​

Prebuilt binaries, a Debian package, and an RPM package are published on the rolling release page.

info

The rolling release is a pre-release built from the current main branch, not a stable versioned release. Its assets are replaced as main moves, so expect behavior to change between downloads.

Ubuntu 24.04 (x86-64)​

Download enclave_<version>_amd64.deb and install it with APT so the runtime dependencies are resolved:

sudo apt install ./enclave_*_amd64.deb

Fedora Linux (x86-64)​

Download enclave-<version>.x86_64.rpm and install it with DNF so the runtime dependencies are resolved:

sudo dnf install ./enclave-*.x86_64.rpm

Other Linux (x86-64 and arm64)​

Download the binary matching your architecture, enclave-linux-amd64 or enclave-linux-arm64, together with checksums.txt. Verify it and install it into ~/.local/bin, where it can update itself:

sha256sum --check --ignore-missing checksums.txt
install -d ~/.local/bin
install enclave-linux-amd64 ~/.local/bin/enclave

Most distributions put ~/.local/bin on PATH at login once it exists.

macOS​

Use enclave-darwin-arm64 on Apple Silicon and enclave-darwin-amd64 on Intel. Download it together with checksums.txt:

shasum -a 256 --check --ignore-missing checksums.txt
xattr -d com.apple.quarantine ./enclave-darwin-arm64 2>/dev/null || true
install -d ~/.local/bin
install enclave-darwin-arm64 ~/.local/bin/enclave

macOS does not put ~/.local/bin on PATH; add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc.

note

The macOS binaries are unsigned and not notarized. A download through the browser carries a quarantine attribute that makes Gatekeeper refuse to run the binary, and install propagates it, so the xattr step comes first. Downloading with curl or gh release download avoids the attribute in the first place, which is why the command tolerates its absence.

Windows (WSL2)​

There is no native Windows build. The supported path is WSL2:

  1. Install WSL2 with an Ubuntu 24.04 distribution.
  2. Make Docker available inside that distribution, either through Docker Desktop's WSL integration or by installing Docker Engine in the distribution itself.
  3. Follow the Linux instructions above from inside the distribution.

That is all you need to run Enclave from a WSL shell. To run it from PowerShell too, install the Windows launcher as well:

scoop install https://github.com/eclipse-enclave/enclave/releases/download/rolling/enclave.json

enclave.exe forwards every argument to the Linux binary inside the distribution and returns its exit code. It is a launcher, not a native build, so step 3 is still required. Alternatively, download enclave-windows-amd64.zip (or enclave-windows-arm64.zip) from the rolling release and put the extracted enclave.exe on your PATH.

note

Run enclave from a directory inside the distribution, for example \\wsl.localhost\Ubuntu\home\you\project, which PowerShell accepts as a working directory. In cmd.exe, pushd on that path maps it to a drive letter, which works too. A Windows drive path such as C:\Users\you\project is refused by default: it would have to be reached through /mnt/c, where every file access crosses the WSL interop layer and is noticeably slower. Keep the project in the WSL filesystem, for example under ~/.

For the full working-directory rules, environment forwarding, and exit codes, see the Windows reference.

Build from source​

Building from source still works and needs the Go toolchain:

git clone https://github.com/eclipse-enclave/enclave
cd enclave
make build

Updating Enclave​

When run interactively, a standalone binary checks its release channel at most once every 24 hours and reports when a different build is available. Binaries from the rolling release follow the rolling channel, rebuilt from every push to main; official releases will follow stable. Set "update_channel" in the global Enclave config.json to switch. Run enclave self-update to download the binary for your platform, verify it against checksums.txt, and atomically replace the current executable. The checksums guard against corrupted downloads, not against a compromised release. A download that receives no data for 30 seconds is aborted, and Ctrl-C stops it without leaving a partial file behind.

The updater never elevates privileges. A binary in a directory you cannot write, such as one installed with sudo install into /usr/local/bin, is updated by repeating the install procedure above; when a different build is available, Enclave prints the commands that download, verify, and reinstall it instead of suggesting self-update.

Automatic replacement is opt-in. Add "auto_update": true to the global Enclave config.json; project and per-tool settings cannot enable it or change the channel. Checks are skipped for shell completion, structured output, and user commands. On Windows, self-update updates the Linux binary inside WSL2; update the Windows launcher itself by reinstalling its Scoop manifest.

Package and source installs neither check for updates nor self-update. Upgrade .deb and .rpm installs with the package manager, and source checkouts with git pull followed by make install.

note

This is about the Enclave binary itself. enclave update rebuilds tool images with the latest agent CLI, and agent CLIs inside a session refresh on their own schedule; neither replaces the Enclave binary on your host.

Start your first session​

From inside a git repository, launch your coding agent in an isolated container:

enclave

The first interactive run asks which agent to use and saves the answer, so this is the only time you are asked. Enclave then builds the environment, mounts the current folder into a container, and starts your agent against the branch you have checked out. The agent runs at full autonomy with no confirmation prompts, and it stays contained.

To keep parallel sessions from stepping on each other, run each one in its own git worktree. This is plain git, no Enclave-specific setup required:

git worktree add ../myproject-agent -b agent/experiment
cd ../myproject-agent
enclave

See Run against an isolated worktree for more.

Pick a specific agent​

To override the saved answer for a single run, or to change it later:

enclave --tool codex

Resume a previous session​

enclave continue

List active sessions​

enclave ps

What happens under the hood​

  1. Enclave uses the current folder and its checked-out branch, or an isolated git worktree if you started the session from one.
  2. It starts a container with that working directory mounted read/write, along with your tool config and package caches.
  3. With the default Docker backend, a gateway sidecar filters outbound traffic against your network allowlist and logs the connections it proxies and the lookups it blocks, so you can audit them later with enclave network log.

Next steps​

See the CLI Commands reference for the full set of commands you can run, and Configuration to pick a default agent, mount extra directories, or widen the network allowlist per project.