{"id":50787781,"url":"https://github.com/edbeeching/hf-agent-ui","last_synced_at":"2026-06-12T09:03:39.346Z","repository":{"id":356053822,"uuid":"1222620518","full_name":"edbeeching/hf-agent-ui","owner":"edbeeching","description":"Browser control for AI coding sessions across local, remote, and cloud agent hosts.","archived":false,"fork":false,"pushed_at":"2026-06-09T15:02:45.000Z","size":1589,"stargazers_count":2,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T16:28:03.651Z","etag":null,"topics":["ai","claude-code","codex","coding-agents","huggingface-spaces"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edbeeching.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-27T14:42:29.000Z","updated_at":"2026-06-09T15:20:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edbeeching/hf-agent-ui","commit_stats":null,"previous_names":["edbeeching/hf-agent-ui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/edbeeching/hf-agent-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edbeeching%2Fhf-agent-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edbeeching%2Fhf-agent-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edbeeching%2Fhf-agent-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edbeeching%2Fhf-agent-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edbeeching","download_url":"https://codeload.github.com/edbeeching/hf-agent-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edbeeching%2Fhf-agent-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34236554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","codex","coding-agents","huggingface-spaces"],"created_at":"2026-06-12T09:03:38.550Z","updated_at":"2026-06-12T09:03:39.340Z","avatar_url":"https://github.com/edbeeching.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: hf-agent-ui\nsdk: docker\napp_port: 7860\nfullWidth: true\nheader: mini\nhf_oauth: true\nhf_oauth_expiration_minutes: 43200\n---\n\n# hf-agent-ui\n\nBrowser 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.\n\n## Architecture\n\n```text\nBrowser \u003c--WS--\u003e Hub (FastAPI) \u003c--WS--\u003e Agent host (Python) \u003c--stdio--\u003e Claude / Codex CLI\n```\n\n- **Hub**: central FastAPI server, browser UI, agent-host registry, and WebSocket relay.\n- **Agent host**: process running on a local, remote, or container machine. It starts Claude/Codex sessions and connects outbound to the hub.\n\n## Install\n\nInstall from the GitHub repository with `uv`:\n\n```bash\nuv tool install --force --reinstall git+https://github.com/edbeeching/hf-agent-ui.git\n```\n\nIf you previously installed the project as `switch`, remove the old tool and use the new command name:\n\n```bash\nuv tool uninstall switch\nuv tool install --force --reinstall git+https://github.com/edbeeching/hf-agent-ui.git\nhf-agent-ui --help\n```\n\nUpdate an installed copy:\n\n```bash\nhf-agent-ui update\n```\n\n## Quick Start\n\nStart the hub:\n\n```bash\nhf-agent-ui hub\n```\n\nOpen `http://localhost:9341`.\n\nFor single-machine development or debugging, start the hub with a local agent host:\n\n```bash\nhf-agent-ui hub --local-agent-host\n```\n\nTo connect another machine to a hub:\n\n```bash\nhf-agent-ui host --hub http://\u003chub-host\u003e:9341\n```\n\nBy default `hf-agent-ui hub` binds to `127.0.0.1`. To expose it on a network interface, configure browser auth first:\n\n```bash\nexport HF_AGENT_UI_BROWSER_TOKEN=\u003cbrowser-token\u003e\nhf-agent-ui hub --host 0.0.0.0\n```\n\nOpen the UI once with:\n\n```text\nhttp://\u003chub-host\u003e:9341/#uiToken=\u003cbrowser-token\u003e\n```\n\n`--allow-insecure` can be used for trusted local-network experiments, but it exposes browser control of connected agent hosts.\n\n## Environments\n\n| Environment | Branch | Space | URL | Deploy behavior |\n|-------------|--------|-------|-----|-----------------|\n| Development | `main` | `edbeeching/hf-agent-ui-dev` | `https://edbeeching-hf-agent-ui-dev.hf.space` | Auto-deploy after `main` CI passes |\n| Production | `prod` | `edbeeching/hf-agent-ui` | `https://edbeeching-hf-agent-ui.hf.space` | Manual deploy from `prod` with explicit production confirmation |\n\nFeature work should land through PRs into `main`. Production release candidates should be PRs from `main` into `prod` after the dev Space has been validated.\n\nProduction deploys are not automatic: the deploy workflow must be run manually from `prod` with `target=production` and the exact confirmation phrase `deploy production`.\n\n## Hugging Face Spaces\n\nBoth Spaces are private Docker Spaces using the front matter at the top of this README:\n\n```yaml\nsdk: docker\napp_port: 7860\nhf_oauth: true\n```\n\nEach Space needs:\n\n```bash\nHF_AGENT_UI_AUTH_MODE=hf-oauth\nHF_AGENT_UI_TRUST_PROXY_AUTH=1\nHF_AGENT_UI_SPACE_REPO_ID=\u003cspace-repo-id\u003e\nHF_TOKEN=\u003chf-token-with-space-and-jobs-access\u003e\n```\n\nUse `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.\n\nRecommended Space variable:\n\n```bash\nHF_AGENT_UI_USER_TOKEN_SECRET=\u003cstable-random-secret\u003e\n```\n\n`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.\n\nFor single-user/local deployments without Hugging Face OAuth, keep using a shared host token:\n\n```bash\nHF_AGENT_UI_AUTH_MODE=single\nHF_AGENT_UI_HOST_TOKEN=\u003cenvironment-specific-shared-secret\u003e\n```\n\nFor private/internal single-user Spaces only, you can optionally expose the agent-host token in the web UI copy command:\n\n```bash\nHF_AGENT_UI_UNSAFE_EXPOSE_HOST_TOKEN=1\n```\n\nTo 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:\n\n```bash\nuv tool install --force --reinstall git+https://github.com/edbeeching/hf-agent-ui.git\nexport HF_TOKEN=\u003chf-token\u003e\nhf-agent-ui host --hub https://\u003cspace-subdomain\u003e.hf.space --token \u003ccopy-from-ui\u003e\n```\n\nThe public Space names are:\n\n```text\nDevelopment: https://edbeeching-hf-agent-ui-dev.hf.space\nProduction:  https://edbeeching-hf-agent-ui.hf.space\n```\n\n### Cloud Agent Hosts\n\nCloud 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.\n\nOptional Space variables:\n\n```bash\nHF_AGENT_UI_JOBS_NAMESPACE=edbeeching\nHF_AGENT_UI_JOBS_DEFAULT_IMAGE=python:3.12\nHF_AGENT_UI_JOBS_DEFAULT_FLAVOR=cpu-basic\nHF_AGENT_UI_JOBS_DEFAULT_TIMEOUT=2h\n```\n\nThe 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.\n\n## Release Flow\n\n1. Create a feature branch from `main`.\n2. Open a PR into `main`.\n3. Merge after CI passes; the dev Space deploys automatically.\n4. Validate `https://edbeeching-hf-agent-ui-dev.hf.space`.\n5. Open a PR from `main` into `prod`.\n6. Merge after CI passes.\n7. Manually run `Deploy HF Space` from the `prod` branch.\n8. Set `target=production` and `confirm_production=deploy production`.\n\nThe GitHub workflow `Deploy HF Space` selects the Space target from the branch that passed CI:\n\n- successful `main` push CI deploys to `edbeeching/hf-agent-ui-dev`.\n- manual confirmed `prod` workflow runs deploy to `edbeeching/hf-agent-ui`.\n\nThe workflow uses the GitHub Actions repository secret `HF_TOKEN` to upload to both Spaces.\n\n## CLI Reference\n\n```text\nhf-agent-ui hub    [-p PORT] [--host HOST] [--local-agent-host] [--allow-insecure] [-v]\nhf-agent-ui host   [--hub URL] [--token TOKEN] [--hf-token TOKEN] [-n NAME] [-v]\nhf-agent-ui update Update the installed tool from the GitHub repo\n```\n\n## Development\n\n```bash\ngit clone https://github.com/edbeeching/hf-agent-ui.git\ncd hf-agent-ui\nuv tool install --force --editable .\n```\n\nThis links the `hf-agent-ui` command to your local checkout. Python changes take effect immediately.\n\nRun the all-in-one local dev command:\n\n```bash\nhf-agent-ui dev\n```\n\nRebuild the production web bundle after frontend changes:\n\n```bash\ncd hf_agent_ui/web\nnpm install\nnpm run build\ncp -r dist/* ../hub/static/\n```\n\nRun checks before opening a PR:\n\n```bash\nuv run --frozen pytest\ncd hf_agent_ui/web \u0026\u0026 npm run lint \u0026\u0026 npm run build\ndiff -qr hf_agent_ui/web/dist hf_agent_ui/hub/static\n```\n\n### Worktrees\n\nKeep local worktrees inside the repo under `.worktrees/` so sandboxed coding agents can read and write them without needing permissions for sibling directories:\n\n```bash\nmkdir -p .worktrees\ngit worktree add .worktrees/\u003cname\u003e -b \u003cbranch\u003e origin/main\n```\n\nThe `.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.\n\n## Supported Tools\n\n| Tool | Status | Notes |\n|------|--------|-------|\n| Claude Code | Supported | Full bidirectional streaming via stream-json |\n| Codex CLI | Supported | Fire-and-forget exec with resume for follow-ups |\n\n## Security Notes\n\n- Keep dev and prod OAuth client secrets and `HF_AGENT_UI_USER_TOKEN_SECRET` values separate.\n- In single-user mode, keep dev and prod `HF_AGENT_UI_HOST_TOKEN` values separate.\n- Do not expose `HF_AGENT_UI_UNSAFE_EXPOSE_HOST_TOKEN=1` outside trusted private single-user deployments.\n- Cloud agent hosts are intentionally powerful; only launch trusted images with the credentials needed for the intended work.\n- See [SECURITY.md](SECURITY.md) for the current security posture and reporting guidance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedbeeching%2Fhf-agent-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedbeeching%2Fhf-agent-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedbeeching%2Fhf-agent-ui/lists"}