Highflame Forge

Run coding agents like Claude Code in isolated, policy-enforced cloud sandboxes.

forge is a CLI client of the hosted Forge control plane. You sign in, launch an agent in an isolated sandbox, and never put cloud-provider credentials on your laptop. Requires Python 3.12+ on macOS or Linux.

Install

forge is a console script. Install it as a tool so the forge binary lands on your PATH (usually ~/.local/bin on Linux):

uv tool install highflame-forge

If the next prompt says command not found, that directory is not on PATH yet:

uv tool update-shell
# then open a new terminal, or: export PATH="$HOME/.local/bin:$PATH"

uv pip install highflame-forge only installs into the active virtualenv. The script then lives at .venv/bin/forge and is invisible until you source .venv/bin/activate, or you run uv run --with highflame-forge forge ….

Alternatively:

pipx install highflame-forge

First run

forge login
forge connect
forge create --harness claude-code

1. forge login opens a browser and stores credentials for this machine. Account and project are fixed at sign-in; switch project by signing in again with --project NAME.
2. forge connect authorizes GitHub so private repos clone. Skip it for public repos — forge claude will also prompt the first time it meets a private repo.
3. forge create --harness claude-code always starts a new sandbox. Run it from a git checkout and that repo is cloned in (current branch, unless you pass --repo / --ref). It prints an id; open a shell with forge shell --id <id>.

Day to day, use forge claude from the checkout instead. It reattaches to the workspace you already have, and launches one if you do not.

cd ~/src/my-repo
forge claude

Arguments after forge claude are passed through to claude. Put -- first for any that Forge would otherwise read as its own.

On a machine with no browser (typically SSH into a dev box):

forge login --headless

Commands

forge --help is the published surface. There is no forge train, forge sweep, forge estimate, or forge gpus.

Account

forge login                 # sign in through your browser
forge login --headless      # print a code to approve from another device
forge login --project NAME  # sign in to this project (name, slug, or id)
forge logout                # discard this profile's stored credentials
forge whoami                # identity, project, and which control plane
forge connect               # GitHub, so private repos work

Workspaces

forge claude                       # Claude Code; reattaches if one is running
forge claude --id ID               # attach to a specific sandbox
forge shell                        # interactive shell (your only sandbox)
forge shell --id ID                # name the sandbox when you have more than one
forge shell --id ID pwd            # one-off remote command
forge create --harness claude-code # always a fresh sandbox
forge list                         # running sandboxes
forge kill SANDBOX_ID              # shut one down (name it; see forge list)
forge workspaces                   # saved filesystems (outlive the sandbox)

create is the explicit verb: you pick the agent. Other harnesses that are wired today:

forge create --harness codex
forge create --harness python --entrypoint agent.py
forge create --harness langgraph

python and langgraph run your agent. The repo comes from your checkout, its dependencies are installed at boot, and inference is governed the same way as every other harness — with no Highflame-specific code in it.

See forge create --help for the full harness list, egress bundles (--policy-bundle), isolation floor (--isolation), and billing flags (--subscription, --byok, --key-free, --direct). Names that are not wired yet fail rather than provision a broken sandbox.

Configuration

The CLI talks HTTPS to the control plane. It does not take cloud-provider credentials. Optional overrides:

# Which stored login to use (also: forge --profile NAME …)
FORGE_PROFILE=default

# Set at login if you are not on the default deployment
FORGE_API_URL=https://api-dev.highflame.dev
FORGE_AUTH_URL=https://studio-dev.highflame.dev

--api-url and --auth-url live on forge login only. Switching deployments is a re-login, so a token minted against one environment is never sent to another.

Development

git clone https://github.com/highflame-ai/highflame-forge.git
cd highflame-forge
uv sync --extra dev

uv run pytest tests/
uv run mypy src/highflame_forge
uv run ruff check src/

License

MIT License — see LICENSE for details.