https://github.com/hoveychen/claw-workspace
Self host docker container to work with agent remotely.
https://github.com/hoveychen/claw-workspace
claude-code distributed paas-services vscode
Last synced: 3 months ago
JSON representation
Self host docker container to work with agent remotely.
- Host: GitHub
- URL: https://github.com/hoveychen/claw-workspace
- Owner: hoveychen
- License: apache-2.0
- Created: 2026-03-26T10:46:21.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-04T14:54:41.000Z (3 months ago)
- Last Synced: 2026-04-04T17:03:47.265Z (3 months ago)
- Topics: claude-code, distributed, paas-services, vscode
- Language: Go
- Homepage: https://hoveychen.github.io/claw-workspace/
- Size: 714 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Run multiple Claude Code agents across distributed machines, with centralized account management and task dispatch.
## Why Claw Workspace?
If you're a Claude Code user who wants to scale beyond a single machine -- running multiple agents on different servers, sharing Claude accounts across a team, or dispatching tasks to a fleet of agents -- Claw Workspace handles the hard parts:
- **Account Pooling** -- Add multiple Claude accounts (Pro/Max) and let the system automatically load-balance across them. When one account hits rate limits, agents seamlessly rotate to another.
- **Distributed Agents** -- Deploy agent containers on any machine (local, cloud, behind NAT). Each agent gets a full VS Code + Claude Code environment accessible via browser.
- **Task Dispatch** -- Send tasks to agents programmatically or from the hub's own Claude Code environment. The hub's master agent can delegate subtasks to remote agents automatically.
- **Shared Filesystem** -- Built-in JuiceFS support gives all agents access to a shared filesystem backed by MinIO + Redis.
- **Web Dashboard** -- Monitor accounts, agents, tasks, and rate limits from a single admin UI.
## Architecture
## Quick Start
### Prerequisites
- Docker and Docker Compose
- At least one Claude account with an active Pro or Max subscription
### 1. Configure Environment
```bash
git clone https://github.com/hoveychen/claw-workspace.git
cd claw-workspace
# Copy example env files
cp .env.hub.example .env.hub
cp .env.agent.example .env.agent
```
Edit `.env.hub` with your settings:
```bash
# Generate an encryption key for storing OAuth tokens
HUB_ENCRYPTION_KEY=$(openssl rand -hex 32)
# Choose passwords
HUB_ADMIN_PASSWORD=your-admin-password
AGENT_SECRET=your-shared-secret
# Single secret for Redis + MinIO (JuiceFS shared filesystem)
JUICEFS_SECRET=your-storage-password
# Your email (for hub's built-in agent)
HUB_ADMIN_EMAIL=you@example.com
```
### 2. Start the Hub
```bash
docker compose -f docker-compose.hub.yml --env-file .env.hub up -d
```
This starts the hub with Redis and MinIO (for shared filesystem). The hub is accessible at `http://localhost:9090`.
### 3. Add a Claude Account
Open the hub dashboard at `http://localhost:9090` and log in with your admin password. Go to **Accounts** and click **Add Account** -- this starts an OAuth flow that opens your browser to authorize with Claude. Once authorized, the hub stores and manages your tokens automatically -- you never need to log in again on each agent.
### 4. Deploy Agents
On any machine that can reach the hub:
```bash
docker compose -f docker-compose.agent-cpu.yml --env-file .env.agent up -d
```
Edit `.env.agent` to point to your hub:
```bash
HUB_HOST=your-hub-host # URLs are derived automatically
AGENT_SECRET=your-shared-secret # must match the hub
JUICEFS_SECRET=your-storage-password # must match the hub
AGENT_NAME=agent-1
OWNER_EMAIL=you@example.com
```
The agent registers with the hub, receives Claude credentials automatically, and is ready to use. Access its VS Code environment at `http://agent-host:8081`.
#### GPU Support
If your agent needs NVIDIA GPU access (e.g., for CUDA workloads), add the GPU override file:
```bash
# Use GPU 0
docker compose -f docker-compose.agent-gpu.yml --env-file .env.agent up -d
# Use a different GPU
GPU_DEVICE_ID=2 docker compose -f docker-compose.agent-gpu.yml --env-file .env.agent up -d
```
Requires [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) on the host. See [Configuration](https://hoveychen.github.io/claw-workspace/configuration/) for details.
### 5. Use the Fleet
The hub dashboard at `http://localhost:9090` gives you full control:
- **Agents** -- Monitor status, open VS Code in browser, reassign accounts
- **Accounts** -- View health, rate limit utilization, enable/disable accounts
- **Tasks** -- Dispatch tasks to agents, view output and cost, stop or resume
- **Sessions** -- Start multi-turn interactive sessions with agents
- **Files** -- Browse shared datasets and results across all agents
You can also use the hub's built-in Claude Code environment (at `http://localhost:8080`) which can automatically delegate work to remote agents via `fleet-cli`.
## Adding More Accounts
For better throughput, add multiple Claude accounts from the **Accounts** page in the dashboard. The hub automatically load-balances across accounts and rotates when one hits rate limits.
## Documentation
Full documentation: [https://hoveychen.github.io/claw-workspace/](https://hoveychen.github.io/claw-workspace/)
- [Getting Started](https://hoveychen.github.io/claw-workspace/getting-started/) -- Detailed setup guide
- [Configuration](https://hoveychen.github.io/claw-workspace/configuration/) -- All environment variables
- [Architecture](https://hoveychen.github.io/claw-workspace/architecture/) -- How it works under the hood
## Building from Source
If you prefer to build locally instead of using pre-built images:
```bash
make build # Build all Go binaries
make docker # Build Docker images locally
make test # Run tests
```
## License
Apache License 2.0. See [LICENSE](LICENSE).