Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .cass/playbook.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Project-specific playbook rules
# These are merged with your global ~/.cass-memory/playbook.yaml
# Project rules take precedence over global rules
schema_version: 2
name: repo-playbook
description: Project-specific rules for this repository
metadata:
createdAt: 2026-03-09T04:30:43.156Z
totalReflections: 0
totalSessionsProcessed: 0
deprecatedPatterns: []
bullets: []
44 changes: 44 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Core control-plane settings
OCTW_DB_URL=postgresql+asyncpg://octw:octw@octw-db:5432/octw
OCTW_REDIS_URL=redis://octw-cache:6379/0
OCTW_PUBLIC_BASE_URL=https://octw.example.com
OCTW_SERVER_NAME=octw.example.com
OCTW_EDGE_DOMAIN=octw.example.com
OCTW_API_INTERNAL_BASE_URL=http://octw-api:8000
OCTW_TRUSTED_PROXY_ENABLED=true
OCTW_TRUSTED_PROXY_USER_HEADER=X-Forwarded-Email
OCTW_TRUSTED_PROXY_IPS=172.30.0.0/24
OCTW_DEFAULT_PROVIDER=zai

# Secrets
# Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
OCTW_JWT_SECRET=replace-with-strong-random-token
# Generate with: python3 -c "import os; print(os.urandom(32).hex())"
OCTW_KEK=replace-with-64-hex-character-kek

# Shared provider API keys (set at least one)
OCTW_ZAI_API_KEY=
OCTW_MOONSHOT_API_KEY=
OCTW_MINIMAX_API_KEY=

# oauth2-proxy base settings
# Valid providers include: oidc, keycloak-oidc, google
OCTW_OIDC_PROVIDER=oidc
# Config file under configs/oauth2-proxy/ used by the oauth2-proxy container.
OCTW_OIDC_CONFIG_FILE=oauth2-proxy.cfg
# Required for generic OIDC and keycloak-oidc. Leave blank for google.
OCTW_OIDC_ISSUER_URL=https://issuer.example.com/realms/octw
OCTW_OIDC_CLIENT_ID=octw
OCTW_OIDC_CLIENT_SECRET=replace-with-oidc-client-secret
# Generate with: python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))"
OCTW_OIDC_COOKIE_SECRET=replace-with-base64-cookie-secret
# Restrict login to your workspace domain. Use * only for isolated test environments.
OCTW_OIDC_EMAIL_DOMAINS=example.com
# Allow oauth2-proxy redirects back to this host. Prefix subdomains with a dot.
OCTW_OIDC_WHITELIST_DOMAINS=.example.com

# Provider-specific examples live in:
# configs/oauth2-proxy/keycloak.example.cfg
# configs/oauth2-proxy/google-workspace.example.cfg
# For Google Workspace group checks, place the Admin SDK service account JSON at:
# configs/oauth2-proxy/credentials/google-admin-sdk.json
156 changes: 110 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,57 +1,128 @@
# OCTW — OpenClaw Tenant Wrapper

OCTW is a multi-tenant abstraction layer that provisions and operates multiple independent [OpenClaw](https://github.com/openclaw/openclaw) installations on a single host. Each tenant gets its own isolated OpenClaw gateway, network, filesystem, credentials, and webchat — using the upstream container image without forking.
OCTW provisions and operates multiple isolated [OpenClaw](https://github.com/openclaw/openclaw) installations on one host. This branch adds a browser-first app flow: reverse-proxy OIDC login, one-click tenant deployment, verified readiness, wake-on-resume, and a minimal OCTW-hosted chat UI.

## Quick Start

### Prerequisites

- Docker (with compose plugin)
- [uv](https://docs.astral.sh/uv/) (for CLI and development)
- Docker Engine with the Compose plugin
- [uv](https://docs.astral.sh/uv/) for local development and tests
- At least one supported model provider API key
- A public DNS name that points to the VM
- OIDC client credentials for your IdP

### 1. Clone and prepare the host
### 1. Prepare the host

```bash
git clone https://github.com/kumanday/OCTW.git && cd OCTW
git clone https://github.com/kumanday/OCTW.git
cd OCTW

sudo mkdir -p /var/lib/octw /etc/octw
sudo chown $USER /var/lib/octw
sudo chown "$USER" /var/lib/octw
sudo python3 -c "import os; open('/etc/octw/master.key','wb').write(os.urandom(32))"
sudo chown $USER /etc/octw/master.key
sudo chown "$USER" /etc/octw/master.key
sudo chmod 600 /etc/octw/master.key
```

### 2. Configure provider API keys
### 2. Create `.env`

Set one or more LLM provider keys. At least one is required:
```bash
cp .env.example .env
```

Fill in these values at minimum:

- `OCTW_KEK`
- `OCTW_JWT_SECRET`
- `OCTW_PUBLIC_BASE_URL`
- `OCTW_SERVER_NAME`
- `OCTW_TRUSTED_PROXY_ENABLED=true`
- one or more provider API keys such as `OCTW_ZAI_API_KEY`
- `OCTW_OIDC_CLIENT_ID`
- `OCTW_OIDC_CLIENT_SECRET`
- `OCTW_OIDC_COOKIE_SECRET`

Useful generators:

```bash
export OCTW_ZAI_API_KEY="your-zai-key" # Z.ai GLM Coding Plan
export OCTW_MOONSHOT_API_KEY="your-moonshot-key" # Moonshot AI Kimi Coding Plan
export OCTW_MINIMAX_API_KEY="your-minimax-key" # MiniMax Coding Plan
python3 -c "import os; print(os.urandom(32).hex())"
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))"
```

### 3. Pick an OIDC provider profile

The stack now includes both public ingress and OIDC inside Docker:

- `octw-proxy` terminates HTTPS and routes requests
- `octw-oidc` runs `oauth2-proxy`

Base oauth2-proxy settings live in [configs/oauth2-proxy/oauth2-proxy.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/oauth2-proxy.cfg).

Provider examples:

- Keycloak: [configs/oauth2-proxy/keycloak.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/keycloak.example.cfg)
- Google Workspace: [configs/oauth2-proxy/google-workspace.example.cfg](/Users/magos/dev/kumanday/OCTW/configs/oauth2-proxy/google-workspace.example.cfg)

Typical Keycloak settings in `.env`:

```dotenv
OCTW_OIDC_PROVIDER=keycloak-oidc
OCTW_OIDC_ISSUER_URL=https://keycloak.example.com/realms/octw
OCTW_OIDC_EMAIL_DOMAINS=example.com
OCTW_OIDC_WHITELIST_DOMAINS=.example.com
```

### 3. Launch the stack
Typical Google Workspace settings in `.env`:

```dotenv
OCTW_OIDC_PROVIDER=google
OCTW_OIDC_ISSUER_URL=
OCTW_OIDC_EMAIL_DOMAINS=example.com
OCTW_OIDC_WHITELIST_DOMAINS=.example.com
```

If you want Google Group checks, place the Admin SDK service account JSON at `configs/oauth2-proxy/credentials/google-admin-sdk.json` and copy the relevant settings from the Google example config.

### 4. Launch the stack

```bash
export OCTW_KEK=$(python3 -c "print(open('/etc/octw/master.key','rb').read().hex())")
export OCTW_JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
docker compose up -d
docker compose up -d --build
```

This starts four services:
This starts six services:

| Service | Port | Purpose |
|---|---|---|
| **octw-api** | 8000 | REST API and one-click provisioning |
| **octw-edge** | 8443 | Tenant proxy with wake-on-request |
| **octw-db** | 5432 | PostgreSQL (metadata, secrets, audit) |
| **octw-cache** | 6379 | Redis (sessions, locks) |
| `octw-proxy` | `80`, `443` | Public HTTPS ingress and routing |
| `octw-oidc` | internal | `oauth2-proxy` for OIDC login/session |
| `octw-api` | `127.0.0.1:8000` | API, browser app, provisioning workflow |
| `octw-edge` | `127.0.0.1:8443` | Auth-aware tenant HTTP and WebSocket proxy |
| `octw-db` | `5432` | PostgreSQL metadata store |
| `octw-cache` | `6379` | Redis sessions and locks |

If `configs/certs/fullchain.pem` and `configs/certs/privkey.pem` do not exist, `octw-proxy` generates an ephemeral self-signed certificate inside the container for bootstrap only. Mount real cert files in `configs/certs/` for production.

### 5. Open the browser app

Open:

```text
https://octw.example.com/app
```

The browser flow is:

### 4. Provision a tenant
1. `octw-proxy` sends the request through `octw-oidc`
2. OCTW boots or refreshes the local `octw_session` cookie from the trusted forwarded email header
3. `POST /api/v1/app/deploy-or-resume` creates or resumes the user's single tenant
4. OCTW verifies the OpenClaw tenant before returning success
5. The browser connects to `/t/{slug}/ws` through `octw-edge` and lands in chat

### 6. Operator / CLI provisioning still works

```bash
# Authenticate
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com"}' | jq -r .dev_token)
Expand All @@ -60,35 +131,28 @@ JWT=$(curl -s -X POST http://localhost:8000/api/v1/auth/verify \
-H 'Content-Type: application/json' \
-d "{\"token\":\"$TOKEN\"}" | jq -r .access_token)

# One-click provision
curl -s -X POST http://localhost:8000/api/v1/provision \
-H "Authorization: Bearer $JWT" \
-H 'Content-Type: application/json' \
-d '{"slug":"acme", "name":"Acme Corp", "provider":"zai"}' | jq
```

Response:
The provision response now includes readiness verification:

```json
{
"tenant_id": "...",
"slug": "acme",
"status": "running",
"provider": "zai",
"model": "zai-coding/glm-5",
"url": "https://octw.example.com/acme/"
"model": "zai/glm-5",
"url": "https://octw.example.com/acme/",
"verification_status": "verified",
"verification_error": null
}
```

The tenant's OpenClaw webchat is accessible at `https://octw.example.com/acme/`.

### 5. List available providers

```bash
curl -s http://localhost:8000/api/v1/provision/providers \
-H "Authorization: Bearer $JWT" | jq
```

## CLI
## Operator CLI

```bash
uv sync
Expand All @@ -97,19 +161,19 @@ uv run octw tenant status <tenant-id>
uv run octw tenant stop <tenant-id>
```

See [docs/cli.md](docs/cli.md) for the full command reference.
See [docs/cli.md](/Users/magos/dev/kumanday/OCTW/docs/cli.md).

## Documentation

| Document | Contents |
|---|---|
| [Architecture](docs/architecture.md) | Component overview, isolation model, data flow |
| [API Reference](docs/api.md) | All REST endpoints with request/response examples |
| [Providers](docs/providers.md) | Supported LLM providers, adding new ones |
| [Configuration](docs/configuration.md) | All environment variables and defaults |
| [Security](docs/security.md) | Threat model, secret strategy, container hardening |
| [CLI Reference](docs/cli.md) | Operator command-line tool |
| [Deployment](docs/deployment.md) | Production setup, Docker Compose, development mode |
| [docs/architecture.md](/Users/magos/dev/kumanday/OCTW/docs/architecture.md) | Control-plane and tenant data flow |
| [docs/api.md](/Users/magos/dev/kumanday/OCTW/docs/api.md) | Browser app, operator API, and internal endpoints |
| [docs/configuration.md](/Users/magos/dev/kumanday/OCTW/docs/configuration.md) | Environment variables and proxy config files |
| [docs/deployment.md](/Users/magos/dev/kumanday/OCTW/docs/deployment.md) | Compose deployment, OIDC setup, verification |
| [docs/security.md](/Users/magos/dev/kumanday/OCTW/docs/security.md) | Reverse-proxy auth, trusted-proxy boundaries, secrets |
| [docs/providers.md](/Users/magos/dev/kumanday/OCTW/docs/providers.md) | Supported model providers |
| [docs/cli.md](/Users/magos/dev/kumanday/OCTW/docs/cli.md) | Operator CLI reference |

## Running Tests

Expand All @@ -119,4 +183,4 @@ uv run pytest tests/ -v

## License

See [LICENSE](LICENSE).
See [LICENSE](/Users/magos/dev/kumanday/OCTW/LICENSE).
Empty file added configs/certs/.gitkeep
Empty file.
98 changes: 98 additions & 0 deletions configs/nginx/default.conf.template
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}

server {
listen 8080;
server_name ${OCTW_SERVER_NAME};
port_in_redirect off;
return 301 https://$host$request_uri;
}

server {
listen 8443 ssl;
http2 on;
server_name ${OCTW_SERVER_NAME};
port_in_redirect off;

ssl_certificate ${OCTW_SSL_CERT_FILE};
ssl_certificate_key ${OCTW_SSL_KEY_FILE};
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_protocols TLSv1.2 TLSv1.3;

proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port 443;

location ^~ /oauth2/ {
proxy_pass http://octw-oidc:4180;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header X-Scheme https;
}

location = /oauth2/auth {
internal;
proxy_pass http://octw-oidc:4180/oauth2/auth;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header Content-Length "";
proxy_pass_request_body off;
}

error_page 401 = @oauth2_signin;

location @oauth2_signin {
return 302 /oauth2/start?rd=$scheme://$http_host$request_uri;
}

location = /health {
proxy_pass http://octw-api:8000/health;
}

location = / {
return 302 /app;
}

location ^~ /app {
auth_request /oauth2/auth;
auth_request_set $user_email $upstream_http_x_auth_request_email;
proxy_set_header X-Forwarded-Email $user_email;
proxy_pass http://octw-api:8000;
}

location ^~ /api/v1/app/ {
auth_request /oauth2/auth;
auth_request_set $user_email $upstream_http_x_auth_request_email;
proxy_set_header X-Forwarded-Email $user_email;
proxy_read_timeout 300s;
proxy_send_timeout 300s;
proxy_pass http://octw-api:8000;
}

location /t/ {
auth_request /oauth2/auth;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_pass http://octw-edge:8443;
}

location /oauth2/sign_out {
proxy_pass http://octw-oidc:4180/oauth2/sign_out;
}

location ~ ^/[a-z0-9][a-z0-9-]*/? {
Comment thread
kumanday marked this conversation as resolved.
Resolved
auth_request /oauth2/auth;
Comment thread
kumanday marked this conversation as resolved.
Resolved
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_pass http://octw-edge:8443;
}

location / {
return 404;
}
}
Empty file.
Loading
Loading