https://github.com/edbeeching/hf-agent-ui
Browser control for AI coding sessions across local, remote, and cloud agent hosts.
https://github.com/edbeeching/hf-agent-ui
ai claude-code codex coding-agents huggingface-spaces
Last synced: 12 days ago
JSON representation
Browser control for AI coding sessions across local, remote, and cloud agent hosts.
- Host: GitHub
- URL: https://github.com/edbeeching/hf-agent-ui
- Owner: edbeeching
- License: mit
- Created: 2026-04-27T14:42:29.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-09T15:02:45.000Z (15 days ago)
- Last Synced: 2026-06-09T16:28:03.651Z (15 days ago)
- Topics: ai, claude-code, codex, coding-agents, huggingface-spaces
- Language: Python
- Size: 1.52 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
---
title: hf-agent-ui
sdk: docker
app_port: 7860
fullWidth: true
header: mini
hf_oauth: true
hf_oauth_expiration_minutes: 43200
---
# hf-agent-ui
Browser control for AI coding sessions. hf-agent-ui manages Claude Code and Codex CLI sessions across local machines, remote servers, and cloud/container agent hosts from one web UI.
## Architecture
```text
Browser <--WS--> Hub (FastAPI) <--WS--> Agent host (Python) <--stdio--> Claude / Codex CLI
```
- **Hub**: central FastAPI server, browser UI, agent-host registry, and WebSocket relay.
- **Agent host**: process running on a local, remote, or container machine. It starts Claude/Codex sessions and connects outbound to the hub.
## Install
Install from the GitHub repository with `uv`:
```bash
uv tool install --force --reinstall git+https://github.com/edbeeching/hf-agent-ui.git
```
If you previously installed the project as `switch`, remove the old tool and use the new command name:
```bash
uv tool uninstall switch
uv tool install --force --reinstall git+https://github.com/edbeeching/hf-agent-ui.git
hf-agent-ui --help
```
Update an installed copy:
```bash
hf-agent-ui update
```
## Quick Start
Start the hub:
```bash
hf-agent-ui hub
```
Open `http://localhost:9341`.
For single-machine development or debugging, start the hub with a local agent host:
```bash
hf-agent-ui hub --local-agent-host
```
To connect another machine to a hub:
```bash
hf-agent-ui host --hub http://:9341
```
By default `hf-agent-ui hub` binds to `127.0.0.1`. To expose it on a network interface, configure browser auth first:
```bash
export HF_AGENT_UI_BROWSER_TOKEN=
hf-agent-ui hub --host 0.0.0.0
```
Open the UI once with:
```text
http://:9341/#uiToken=
```
`--allow-insecure` can be used for trusted local-network experiments, but it exposes browser control of connected agent hosts.
## Environments
| Environment | Branch | Space | URL | Deploy behavior |
|-------------|--------|-------|-----|-----------------|
| Development | `main` | `edbeeching/hf-agent-ui-dev` | `https://edbeeching-hf-agent-ui-dev.hf.space` | Auto-deploy after `main` CI passes |
| Production | `prod` | `edbeeching/hf-agent-ui` | `https://edbeeching-hf-agent-ui.hf.space` | Manual deploy from `prod` with explicit production confirmation |
Feature work should land through PRs into `main`. Production release candidates should be PRs from `main` into `prod` after the dev Space has been validated.
Production deploys are not automatic: the deploy workflow must be run manually from `prod` with `target=production` and the exact confirmation phrase `deploy production`.
## Hugging Face Spaces
Both Spaces are private Docker Spaces using the front matter at the top of this README:
```yaml
sdk: docker
app_port: 7860
hf_oauth: true
```
Each Space needs:
```bash
HF_AGENT_UI_AUTH_MODE=hf-oauth
HF_AGENT_UI_TRUST_PROXY_AUTH=1
HF_AGENT_UI_SPACE_REPO_ID=
HF_TOKEN=
```
Use `HF_AGENT_UI_SPACE_REPO_ID=edbeeching/hf-agent-ui-dev` for dev and `HF_AGENT_UI_SPACE_REPO_ID=edbeeching/hf-agent-ui` for prod.
Recommended Space variable:
```bash
HF_AGENT_UI_USER_TOKEN_SECRET=
```
`HF_AGENT_UI_USER_TOKEN_SECRET` signs per-user agent-host tokens. If it is omitted, hf-agent-ui falls back to the OAuth client secret.
For single-user/local deployments without Hugging Face OAuth, keep using a shared host token:
```bash
HF_AGENT_UI_AUTH_MODE=single
HF_AGENT_UI_HOST_TOKEN=
```
For private/internal single-user Spaces only, you can optionally expose the agent-host token in the web UI copy command:
```bash
HF_AGENT_UI_UNSAFE_EXPOSE_HOST_TOKEN=1
```
To connect an agent host to a Space, sign in to the Space UI and use the exact copy command shown there. It includes a token scoped to your Hugging Face account:
```bash
uv tool install --force --reinstall git+https://github.com/edbeeching/hf-agent-ui.git
export HF_TOKEN=
hf-agent-ui host --hub https://.hf.space --token
```
The public Space names are:
```text
Development: https://edbeeching-hf-agent-ui-dev.hf.space
Production: https://edbeeching-hf-agent-ui.hf.space
```
### Cloud Agent Hosts
Cloud agent host support through Hugging Face Jobs is implemented behind a hidden frontend flag while the UX is still being iterated. When enabled, the Space-side `HF_TOKEN` and the current user's signed host token are passed server-side to the job; they are not returned to the browser response.
Optional Space variables:
```bash
HF_AGENT_UI_JOBS_NAMESPACE=edbeeching
HF_AGENT_UI_JOBS_DEFAULT_IMAGE=python:3.12
HF_AGENT_UI_JOBS_DEFAULT_FLAVOR=cpu-basic
HF_AGENT_UI_JOBS_DEFAULT_TIMEOUT=2h
```
The default image installs hf-agent-ui from the configured Space snapshot and connects back to the hub. Images used for real sessions must also include Claude Code or Codex CLI and any credentials those tools require.
## Release Flow
1. Create a feature branch from `main`.
2. Open a PR into `main`.
3. Merge after CI passes; the dev Space deploys automatically.
4. Validate `https://edbeeching-hf-agent-ui-dev.hf.space`.
5. Open a PR from `main` into `prod`.
6. Merge after CI passes.
7. Manually run `Deploy HF Space` from the `prod` branch.
8. Set `target=production` and `confirm_production=deploy production`.
The GitHub workflow `Deploy HF Space` selects the Space target from the branch that passed CI:
- successful `main` push CI deploys to `edbeeching/hf-agent-ui-dev`.
- manual confirmed `prod` workflow runs deploy to `edbeeching/hf-agent-ui`.
The workflow uses the GitHub Actions repository secret `HF_TOKEN` to upload to both Spaces.
## CLI Reference
```text
hf-agent-ui hub [-p PORT] [--host HOST] [--local-agent-host] [--allow-insecure] [-v]
hf-agent-ui host [--hub URL] [--token TOKEN] [--hf-token TOKEN] [-n NAME] [-v]
hf-agent-ui update Update the installed tool from the GitHub repo
```
## Development
```bash
git clone https://github.com/edbeeching/hf-agent-ui.git
cd hf-agent-ui
uv tool install --force --editable .
```
This links the `hf-agent-ui` command to your local checkout. Python changes take effect immediately.
Run the all-in-one local dev command:
```bash
hf-agent-ui dev
```
Rebuild the production web bundle after frontend changes:
```bash
cd hf_agent_ui/web
npm install
npm run build
cp -r dist/* ../hub/static/
```
Run checks before opening a PR:
```bash
uv run --frozen pytest
cd hf_agent_ui/web && npm run lint && npm run build
diff -qr hf_agent_ui/web/dist hf_agent_ui/hub/static
```
### Worktrees
Keep local worktrees inside the repo under `.worktrees/` so sandboxed coding agents can read and write them without needing permissions for sibling directories:
```bash
mkdir -p .worktrees
git worktree add .worktrees/ -b origin/main
```
The `.worktrees/` directory is ignored by Git. Avoid placing worktrees next to the repo, such as `../hf-agent-ui-main`, because those paths may sit outside an agent's writable workspace root.
## Supported Tools
| Tool | Status | Notes |
|------|--------|-------|
| Claude Code | Supported | Full bidirectional streaming via stream-json |
| Codex CLI | Supported | Fire-and-forget exec with resume for follow-ups |
## Security Notes
- Keep dev and prod OAuth client secrets and `HF_AGENT_UI_USER_TOKEN_SECRET` values separate.
- In single-user mode, keep dev and prod `HF_AGENT_UI_HOST_TOKEN` values separate.
- Do not expose `HF_AGENT_UI_UNSAFE_EXPOSE_HOST_TOKEN=1` outside trusted private single-user deployments.
- Cloud agent hosts are intentionally powerful; only launch trusted images with the credentials needed for the intended work.
- See [SECURITY.md](SECURITY.md) for the current security posture and reporting guidance.