Cloudflare OS Home

Unofficial self-hosted Cloudflare OS workspace with project-local LiteLLM, Docker Compose, and Tailscale.

日本語 · Documentation · Research Lab · Issues

✨ What this is

Cloudflare OS Home is a reproducible local runtime for exploring Cloudflare OS as an agent-first workspace. It keeps the upstream source, project-local LiteLLM route, Docker Compose networking, Tailscale Serve instructions, and browser QA together in one operational repository.

This is an unofficial integration, not a Cloudflare-hosted product or official distribution. Detailed experiments, screenshots, HyperFrames assets, and feature conclusions live in the separate Cloudflare OS Home Lab repository.

🚀 What you get

• Cloudflare OS source pinned to a known upstream revision.
• Project-local LiteLLM with an OpenAI-compatible endpoint at http://litellm:4000/v1.
• A 26-model configuration template with provider credentials loaded from .env.
• Docker Compose networking that does not depend on an external Open WebUI network.
• Optional tailnet-only HTTPS access through Tailscale Serve.
• Browser QA scripts for model registration, chat persistence, responsive layout, and agentic Gadget creation.
• A separate evidence repository for detailed experiment records and screenshots.

🧭 Choose your path

Goal	Start here
Run the local workspace	Quick start
Understand the containers	Architecture
Reproduce the agent test	Agent smoke test
Configure tailnet-only access	Tailscale access
Read experiment results and screenshots	Cloudflare OS Home Lab
Diagnose a failed setup	Troubleshooting

⚡ Quick start

Prerequisites: Docker Desktop with the Linux engine enabled and PowerShell.

git clone https://github.com/Sunwood-ai-labs/cloudflare-os-home.git
Set-Location cloudflare-os-home
Copy-Item .env.example .env
notepad .env
docker compose up --build -d

Open http://localhost:8877 and create a local account on first use. At minimum, set LITELLM_MASTER_KEY in .env; provider API keys are only required for the routes you intend to call. AWS profile files are optional and are never committed.

Stop the stack with:

docker compose down

Named volumes preserve local Worker state. Use docker compose down -v only when you intentionally want to remove that state.

🔐 Environment and secrets

.env.example is safe to copy, but it is intentionally incomplete. Keep real values in .env:

• LITELLM_MASTER_KEY for the project-local LiteLLM API.
• Provider keys such as ZAI_API_KEY, NVIDIA_API_KEY, and GEMINI_API_KEY when needed.
• CFOS_PUBLIC_BASE_URL and CFOS_BACKEND_HOST when using a non-local browser endpoint.
• AWS profiles only when using the optional Bedrock Mantle routes.

Never commit .env, secrets/, AWS profiles, or browser credentials. See SECURITY.md.

🧩 Architecture

Browser
  │ http://localhost:8877 or a tailnet-only Tailscale URL
  ▼
Cloudflare OS container
  │ http://litellm:4000/v1
  ▼
Project-local LiteLLM container
  │
  ▼
Configured model providers

Cloudflare OS owns the workspace, agent loop, Gadget tools, and reviewable changes. LiteLLM owns OpenAI-compatible model routing. The model itself is interchangeable; the runtime was exercised with glm-4.7 and glm-5.2.

Architecture diagrams

The editable draw.io source is docs/cloudflare-os-architecture.drawio. The exported SVGs are shown below so the architecture is visible directly from the repository README.

Runtime architecture: Docker Compose, Cloudflare OS, Gatekeepers, LiteLLM, and external providers.

Repository structure: the local integration wrapper and the pinned upstream monorepo.

🌐 Tailscale access

Tailscale Serve can provide tailnet-only HTTPS without opening a public Funnel endpoint:

$env:CFOS_PUBLIC_BASE_URL = 'https://<your-tailnet-host>:8877'
$env:CFOS_BACKEND_HOST = '<your-tailnet-host>:8877'
docker compose up -d --force-recreate cloudflare-os
.\scripts\enable-tailscale-serve.ps1

The helper prints the actual tailnet URL. Keep the endpoint private to your tailnet and review the authentication model before sharing it.

🤖 Agent smoke test

The included smoke test asks Cloudflare OS to create a minimal Gadget, write server.js and client.js, execute a test, and report the result. Supply credentials explicitly:

$env:CFOS_USERNAME = 'your-local-account'
$env:CFOS_PASSWORD = 'your-local-password'
$env:BASE_URL = 'http://localhost:8877'
node .\qa\agentic-gadget-smoke.mjs

The run should produce a Gadget draft with Pending changes, Accept changes, and Discard. Detailed interpretation and visual evidence belong in the Cloudflare OS Home Lab.

🧪 Runtime QA

The CI workflow validates the Compose file, QA script syntax, public-payload exclusions, and whitespace. The VitePress documentation build runs in the same workflow. For experiment-level claims, use the Lab QA inventory.

📚 Documentation

• Getting started
• Usage
• Architecture
• Troubleshooting
• Experiment records and evidence

📜 License

The repository is Apache-2.0 licensed. Upstream notices and third-party terms are listed in THIRD-PARTY-NOTICES.md.