Byre

Checked: 2026-07-14

Summary

Byre is an MIT-licensed command-line tool that runs a coding agent in one local Docker or Podman container. It mounts the current project read-write, keeps the rest of the host hidden unless explicitly granted, and generates readable Dockerfiles and run commands so users can inspect or leave the tool.

Problem

Coding agents running directly on a laptop inherit broad file, environment, and credential access. Hand-building a container for each project adds setup, login persistence, file-ownership, and reset work. Byre packages those repeated steps into one local workflow.

How It Works

• byre develop composes configuration, generates an image, builds on a cache miss, and runs the selected agent.
• Configuration cascades from a personal baseline, a reusable template, and project-specific overrides.
• Bundled templates cover Go, Node.js, and Python. Users can inspect, fork, install, and package templates and skills.
• The project mounts at /workspace read-write. Extra mounts and passed environment values require configuration.
• Per-project state volumes keep agent login and history across rebuilds. Disposable cache volumes can hold items such as dependencies.
• byre worktree <name> creates a linked Git worktree and launches a separate container for a parallel agent.
• byre status reports the resolved agent, template, engine, mounts, network posture, ports, skills, volumes, and running container.
• byre dockerfile, byre dockerrun, and byre ejectfirewall expose the generated parts for migration away from Byre.

Security Boundary

• By default, the agent sees the project plus only mounts, environment values, credentials, and skills the user enables.
• Configuration lives outside the writable project so an agent cannot quietly edit it through the repository.
• The agent runs unprivileged with the host user’s user and group IDs baked into the image.
• The boundary is a container sharing the host kernel, not a microVM. The maintainer says it is meant for over-eager or reckless agents, including prompt-injected agents, but not a dedicated attacker with kernel exploits.
• Docker daemon access is effectively host-root access. Mounting the daemon socket removes meaningful containment.
• Skills are trusted code: they can add Dockerfile instructions, launch hooks, mounts, and network behavior.
• --self-edit lets the agent author configuration for the next run and therefore gives it a path to broader host access. Byre warns and shows a diff afterward.

Platforms and Agents

• Hosts: Linux and macOS.
• Engines: rootful Docker or Podman. Rootless Podman was not yet supported.
• Images: Debian-derived bases only.
• Bundled agent skills: Claude Code, Codex, Gemini, and Grok. Other agents can be added through custom skills.
• Installation: Go 1.22+, checksum-verified release script, or Homebrew on macOS.
• Unknown: native Windows support is not documented.

Setup

1. Install Byre and start Docker or Podman.
2. Enter a project folder and run byre develop.
3. Choose a template, agent, and whether supported agents may use shared machine credentials.
4. Log the agent in. By default, the login persists only for that project.
5. Use byre config to add packages, mounts, volumes, skills, ports, or environment values.
6. Check byre status before running with skipped agent permissions.
7. Use byre reset to clear project volumes or byre forget to remove Byre’s host-side state without touching the project tree.

Network and Credentials

• Network access is open by default. An agent can send project data or any credentials it holds to the internet.
• The optional firewall skill changes outbound access to default-deny. A privileged helper enters the container network namespace, installs an allowlist, verifies it, and fails closed before the agent starts.
• Hostname grants resolve to fixed IP addresses at launch. Rotating DNS may break an allowed destination until restart, but the documented failure direction is closed.
• A separate open-network denylist skill blocks selected hosts but is explicitly not a security boundary.
• By default, agent logins live in per-project volumes. Optional shared-auth skills share supported agent credentials across project boxes.
• Shared credentials are readable by any agent in an enabled box and can be exfiltrated.
• Configuration env values are stored in image layers and visible in Docker history. The maintainer says secrets should use agent login flows or credential volumes instead.

Strengths

• One-command local workflow with no hosted control plane or usage charge.
• Explicit grants and a useful status view make the blast radius easier to inspect.
• Generates readable Docker rather than hiding the environment behind a service.
• Persistent agent login, history, and caches reduce repeated setup.
• Worktree support makes parallel local agents straightforward.
• Templates and skills allow a personal toolkit to improve across projects.
• Clear exit path to ordinary Docker commands and files.

Limits and Risks

• Container isolation shares the host kernel and is weaker than a dedicated VM or microVM.
• Open networking is the default; the stronger firewall must be enabled.
• The writable project can still be damaged, deleted, or changed outside the task.
• Docker daemon users can access Byre volumes and the host, regardless of Byre naming conventions.
• Skills, shared authentication, host mounts, environment values, and self-edit mode deliberately widen trust.
• Firewall hostname rules may become stale when providers rotate IPs.
• Rootless Podman and native Windows were not supported or documented at the check date.
• No pricing applies to Byre itself, but it consumes local compute and storage.

Activity and Maturity

• Created 2026-06-29; latest release v0.3.0 published 2026-07-14.
• GitHub showed 10 stars, no forks, an active main branch, and 10 releases from v0.1.2 through v0.3.0 between July 7 and July 14.
• The maintainer labels it a young project with features liable to change quickly and describes it as single-maintainer.
• The rapid release pace shows active work, not stability. Treat configuration and command compatibility as changeable.
• No independent security audit or mature support promise was found.

Best Fit

• A developer who wants a lightweight local guardrail against accidental or over-eager agent behavior.
• Repeated work across many folders where persistent logins, templates, and toolchains save setup time.
• Local worktrees running parallel Claude, Codex, Gemini, or Grok sessions.
• Users who value inspectable Docker output and an easy exit path.

Use a remote machine or microVM instead when hostile-code resistance, kernel separation, or separation from the local network is required.

Comparison Facts

Fact	Byre	Clawk
Isolation	Local Docker/Podman container	Local VM
Kernel boundary	Shares host kernel	Separate guest kernel
Main design	One container per folder	Disposable Linux VM per project
Host access	Explicit mounts; project read-write	Project copied or mounted into VM workflow
Network	Open by default; optional fail-closed allowlist	Allowlist-oriented VM network controls
Parallel work	Git worktree containers	Multiple project VMs
Portability	Can eject to generated Docker	Depends on Clawk’s VM orchestration
Cost	Local resources, open source	Local resources, open source

Byre favors simplicity and transparency. Clawk offers a stronger VM boundary at the cost of heavier machinery.

Hacker News Context

In the Clawk thread, Byre maintainer petesergeant presented it as another solution and highlighted one local container, explicit access grants, readable generated Docker, a normal development workflow, and easy ejection. The comment did not claim equal isolation to Clawk; Byre’s own security documentation clearly says containers are not microVMs.

Unknowns

• Independent security review, audit history, and real-world escape testing.
• Long-term compatibility guarantees and maintenance capacity beyond the single maintainer.
• Native Windows plans and a date for rootless Podman.
• Resource limits or denial-of-service protections beyond what users pass to Docker or Podman.

Sources

• Byre repository and README
• Byre security model
• Byre architecture
• Byre releases
• HN: Clawk discussion
• HN: Byre comment