roke

🏝️ Roke is the island of wizards in Ursula K. Le Guin's Earthsea: a place where power is learned and kept, guarded by a wind that lets no one in uninvited.

Run coding agents, such as Claude Code, Codex or OpenCode, inside a Docker container that only sees the project you are working on. Your $HOME, SSH keys, dotfiles and every other project stay out of the agent's reach.

• Any agent: choose the agent per project or per run. Agents are pluggable, so adding another one is a matter of adding a directory.
• Isolated: the project is the only host directory the agent can write to. Its .git is read-only, and the container runs without sudo, without capabilities and without access to Docker.
• Services on demand: databases, caches, queues, test email, tracing, API mocks, a simulated Kubernetes API and more, each in its own container, with separate data for every project.
• MCP servers: GitHub, Context7 and others, managed like the services and given to whichever agent you use, in its own format.
• Restricted network: by default, the agent only reaches the destinations you allow, with any protocol; roke network blocked shows what was denied and roke network add opens it.
• Per-project tools: languages and tools are installed with mise from the project's mise.toml.
• Semantic code navigation, optionally, with Serena.
• Shareable: your settings live in ~/.config/roke, outside this repository, and can be kept in a private repository of their own.

Quick start

1. Install Docker with the Compose plugin: see Installation for Arch, Debian, Ubuntu and others.

2. Install roke:

   curl -fsSL https://raw.githubusercontent.com/bameda/roke/main/install.sh | bash

3. Choose your default agent: roke agent use claude --global, codex or opencode.

4. Start it in a project, building the image the first time:

   cd ~/src/my-project
   roke build

   The first time, log in from inside the agent; see its README.

Then follow First steps to set up a project with its services and tools.

Everyday use

roke                        # start the agent in the current project
roke continue               # resume its last session
roke -s postgres -p 5173    # this time with a database and the dev server's port
roke shell                  # bash inside the box
roke exec psql              # a single command inside the box
roke urls                   # where the app and the services are
roke service show postgres  # a service: version, address, variables, docs
roke settings edit          # edit the project's settings in your editor
roke service add postgres   # add a service to the project, for good
roke mcp add github         # give the agent an MCP server, for good
roke agent use opencode     # use another agent in the project, for good
roke network blocked        # what the network denied
roke down                   # stop the project's containers (keeps data)
roke help                   # every command

Each project keeps its services, ports and other options in its own directory, ~/.config/roke/projects/<name>/, so day to day roke is usually enough.

Documentation

Guide	What you will find
Installation	Docker on each distribution, installing and updating roke, rootless Docker
First steps	Step-by-step tutorial: adding a project
Usage	Every roke option, ports, git workflow, stopping and resetting
Agents	The available agents, choosing one, how each logs in and is configured, adding another
Configuration	~/.config/roke, keeping it in a private repo, per-project settings, tools, settings reference
Services	The service catalog, how to use each one and how to add your own
MCP servers	The MCP catalog, how they reach each agent and how to add your own
Example projects	Ready-made configurations: Ansible, Helm, Python, Node.js, Go, Rust, Rails, Spring Boot, Clojure
Serena	Semantic code navigation and editing
Network	How the pieces fit, restricted and open mode, allowing destinations
Security	What the container can and cannot reach
Troubleshooting	Common problems, known limitations and maintenance
Development	Running the tests and trying changes

Security in a nutshell

The agent can read and write the project, but nothing else on your machine, and by default it only reaches the network destinations you allow. Anything it writes runs on your host if you later run it there: review the diff before running the project's scripts or committing. Read Security and Network for the details.

Contributing

Contributions are welcome: see CONTRIBUTING.md. To report a security problem, follow SECURITY.md instead of opening an issue.

License

MIT © David Barragán Merino