Getting Started

Quick Start

flamel is a self-hosted web interface for agent CLIs like Claude Code and Codex. Run the server on any Linux machine, connect from web.flamel.dev.

What you need

Docker on a Linux machine — local or VPS
A flamel.dev account
A supported local provider login, such as Claude Code or Codex, configured in your Flamel server

Run the server

shell

docker run -d \
  --name flamel \
  --restart always \
  --privileged \
  -p 8181:8181 \
  -v flamel:/data \
  flameldev/flamel:latest

--privileged is required. flamel uses bubblewrap to sandbox each agent session in an isolated Linux namespace. Without it, sessions won't start.

Register your server

On first start, the server detects it isn't registered and prints a registration URL to its logs:

shell

docker logs flamel

You'll see something like:

output

  flamel server is not registered with flamel.dev.

  Register at:
  https://flamel.dev/register-server?nonce=abc123...&callback_url=...

  Starting server and waiting for registration callback...

Open that URL in your browser. It takes you to flamel.dev where you sign in and confirm the registration. When you confirm, flamel.dev redirects your browser back to your server to complete the handshake — no server-to-server calls, just a browser redirect.

The registration page will ask for your server's URL. If you're on a VPS, enter your public IP or domain (e.g. http://1.2.3.4:8181). For local use, http://localhost:8181 is fine.

Once registered, flamel.dev only ever issues short-lived auth tokens. It never proxies your traffic or sees what happens in your sessions.

Link an agent provider

In the local Flamel UI, use Settings → Claude for Claude Code and Settings → OpenAI for Codex. Provider auth is handled by your server runtime, not by flamel.dev.

Link Git (optional)

Go to Settings → Git Accounts to connect a GitHub or Gitea account. Once linked, agent sessions can clone private repos, push commits, and open PRs without touching SSH keys on the server.

NextHow It Works →