Getting started¶

Run hangar on a laptop in five minutes and give it a first task. This is the one Quickstart; the README repeats its five commands. Concepts explains the words (environment, harness, sandbox, session, job) and what hangar gives you. The changelog says what each release added.

Quickstart¶

Five minutes on a laptop. You need Docker (Docker Desktop, OrbStack or Colima on macOS) and uv (Python 3.12+ is managed by uv).

git clone https://github.com/Sean-Koval/hangar.git && cd hangar
uv sync --all-extras
uv run hangar up        # server, CLI login, the claude-python environment, MCP clients
uv run hangar cred add claude-api --harness claude-code --kind api_key --file anthropic-key.txt
uv run hangar doctor    # every check passes, or names its fix

hangar up does five things:

1. checks that Docker is running;
2. starts the control plane in the background (log: ~/.hangar/server.log);
3. logs the CLI in;
4. builds the claude-python environment (the first build downloads tools, so allow a few minutes);
5. offers to connect each MCP client it finds.

Running it again is safe: it reuses the running server, the saved login and the built images. --env NAME builds other environments, --no-build skips building, and --connect codex connects a client without asking. hangar down stops the server.

Open the console at localhost:8787 to see your fleet, credentials, environments and live terminals (the web console). Local state is in ~/.hangar. If a doctor check fails, follow its fix; uv run hangar doctor --fix applies the supported repairs.

To look around first without Docker or a key, run the demo hangar the front page's recording uses: uv run python docs/assets/front/demo.py. It serves the console on :8787 and prints its token. Then run uv run python docs/assets/front/demo.py ticket in another terminal to label issue #42.

Credentials¶

Use Credentials in the console, or store a key from the CLI as above. Use an API key (an Anthropic Console key, an OpenAI project key, a Claude Team or Enterprise key). Set a spend limit on it in the vendor's console; hangar's own job and daily budgets cap spend inside hangar. For Codex, and for private repositories:

uv run hangar cred add codex-api --harness codex --kind api_key --file openai-key.txt
uv run hangar env build codex-node
uv run hangar cred add gh --harness git --kind git_token --value "$(gh auth token)"

Choose the credential when creating a sandbox, or list its name in your environment's credentials field. Storing a key alone does not attach it to every sandbox.

Jobs, schedules, webhooks and experiments run on API keys only. A personal subscription login (Claude Pro or Max, a ChatGPT sign-in) is for your own interactive sessions, with a warning: see subscription logins.

Connect your client¶

If hangar up did not connect your client, run uv run hangar connect claude-code (or codex, cursor, vscode, gemini, claude-desktop). It adds hangar to the client's own config file, next to your other servers. Its fresh token can reach the MCP endpoints and nothing else:

• hangar (/mcp: jobs, sessions, schedules);
• for Claude Code and Codex, hangar-sandbox (/mcp/sandbox: create_sandbox, exec, files, terminals; the two servers).

Start a new client session so it reads the updated configuration. hangar connect --list shows what's connected; connecting clients covers all options, remote connections and OAuth.

First task¶

In your connected MCP client, ask:

Use hangar to create a claude-python sandbox for https://github.com/YOUR-USER/YOUR-REPO.git. Use the claude-api credential and a new work branch. Run Claude Code to explain the project structure and how to run its tests. Report the sandbox name and findings.

Replace the repository URL with your own. Start with a public repo, or add a Git credential for private repository access. The same from the CLI:

uv run hangar sb create claude-python \
  --name first-task \
  --repo https://github.com/YOUR-USER/YOUR-REPO.git \
  --work-branch hangar/first-task \
  --cred claude-api

uv run hangar sb agent first-task \
  "Explain the project structure and how to run its tests."

Open the sandbox in the console to follow the work in its live terminal. When you finish reviewing it, remove it with uv run hangar sb rm first-task. For Codex, use codex-node and --cred codex-api instead.

Next steps¶

What's new¶

Newest first, up to main today. Each release's page says what changes for a running hangar (release notes); the changelog lists every PR.

Moved from this page¶