Deployment Guides

This page is a collection of How-to guides. Each guide targets a specific deployment goal. Find the one that matches your situation and follow it directly. These guides assume you have already completed Getting Started.

Guides in This Page

How to Deploy VECTOR on a Single Mac

Goal: Production-stable VECTOR instance on an always-on Mac mini or MacBook.

1. Set the machine to never sleep

sudo pmset -a sleep 0
sudo pmset -a displaysleep 0
sudo pmset -a disksleep 0

2. Create a persistent launchd service

Create /Library/LaunchDaemons/ai.skyslab.vector.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.skyslab.vector</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/openclaw</string>
    <string>gateway</string>
    <string>start</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/acevashisth/.openclaw/workspace</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/var/log/vector-gateway.log</string>
  <key>StandardErrorPath</key>
  <string>/var/log/vector-gateway-error.log</string>
</dict>
</plist>

Load and start the service:

sudo launchctl load /Library/LaunchDaemons/ai.skyslab.vector.plist
sudo launchctl start ai.skyslab.vector

3. Verify the service is running

sudo launchctl list | grep vector
# Should show: 0  ai.skyslab.vector

curl -s http://localhost:18789/health
# Should return: {"status":"ok"}

The gateway will now restart automatically after reboots and crashes.

How to Expose VECTOR via Cloudflare Access

Goal: Secure remote access to the ACE Terminal interface, protected by Cloudflare Zero Trust. No open ports on your network.

1. Install cloudflared

brew install cloudflared

2. Authenticate with Cloudflare

cloudflared tunnel login

This opens a browser window. Select your Cloudflare domain and authorize.

3. Create a named tunnel

cloudflared tunnel create vector-gateway

Note the tunnel ID printed (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

4. Create the tunnel config

Create ~/.cloudflared/config.yml:

tunnel: YOUR_TUNNEL_ID_HERE
credentials-file: /Users/acevashisth/.cloudflared/YOUR_TUNNEL_ID_HERE.json

ingress:
  - hostname: ace.yourdomain.ai
    service: http://localhost:3001
  - hostname: vector-api.yourdomain.ai
    service: http://localhost:18789
  - service: http_status:404

5. Create a DNS record

cloudflared tunnel route dns vector-gateway ace.yourdomain.ai
cloudflared tunnel route dns vector-gateway vector-api.yourdomain.ai

6. Configure Cloudflare Access policy

In the Cloudflare Zero Trust dashboard:

  1. Go to Access → Applications → Add an Application
  2. Select Self-hosted
  3. Set the domain to ace.yourdomain.ai
  4. Set the policy: allow only your email address (or your organization's email domain)

7. Start the tunnel

cloudflared tunnel run vector-gateway

To run it as a service:

sudo cloudflared service install
sudo launchctl start com.cloudflare.cloudflared

8. Verify access

Open https://ace.yourdomain.ai in a browser on a different network. You will be redirected to the Cloudflare Access login. After authenticating, you will see the ACE Terminal.

How to Configure Multi-Machine VECTOR with a Shared Workspace

Goal: VECTOR running on a primary machine, with a secondary machine able to read workspace state and run workers.

This configuration requires a network-accessible file share. Both machines must be on the same network or connected via VPN.

1. Share the workspace directory from the primary machine

On the primary Mac:

# Enable SMB file sharing
sudo defaults write /var/db/smb/smb.conf workgroup WORKGROUP
sharing -a ~/.openclaw/workspace -n "vector-workspace"

2. Mount the workspace on the secondary machine

On the secondary Mac:

mkdir -p ~/mnt/vector-workspace
mount -t smbfs //primary-mac-ip/vector-workspace ~/mnt/vector-workspace

3. Configure the secondary machine's openclaw.json

{
  "agent": {
    "id": "secondary",
    "workspace": "/Users/yourusername/mnt/vector-workspace"
  },
  "role": "worker-only"
}

worker-only mode means this machine accepts worker task spawns from the primary but does not run VECTOR or PMs.

4. Register the secondary as a worker node

On the primary machine:

node scripts/register-worker-node.js \
  --hostname secondary-mac-ip \
  --role worker-only \
  --capacity 3

Verify the node appears in the worker pool:

sqlite3 state/vector.db "SELECT * FROM worker_nodes;"

How to Deploy VECTOR in a Docker Container

Goal: Run VECTOR in a container for staging environments, CI, or multi-cloud deployment.

1. Build the VECTOR image

cd ~/.openclaw/workspace
docker build -t skysphere/vector:latest -f deploy/Dockerfile .

2. Create a Docker volume for persistent state

docker volume create vector-state
docker volume create vector-memory

3. Create a secrets environment file

Create ~/.vector-secrets.env (never commit this file):

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENCLAW_GATEWAY_TOKEN=your-gateway-token

4. Run the container

docker run -d \
  --name vector \
  --restart unless-stopped \
  -p 18789:18789 \
  -p 3001:3001 \
  -v vector-state:/app/state \
  -v vector-memory:/app/memory \
  --env-file ~/.vector-secrets.env \
  skysphere/vector:latest

5. Verify the container is running

docker logs vector --tail 20
curl http://localhost:18789/health

Use deploy/docker-compose.yml from the workspace:

docker compose -f deploy/docker-compose.yml up -d

This starts VECTOR, the ACE frontend, and the MCP bridge together.

How to Configure Data Sovereignty for India-Hosted Deployments

Goal: Ensure all data stays within Indian infrastructure — required for government and regulated deployments.

1. Select an India-region cloud provider

Recommended options:

2. Deploy the container to the India region

# Example: AWS ECS deployment in ap-south-1
aws ecs create-service \
  --cluster vector-cluster \
  --service-name vector-production \
  --region ap-south-1 \
  --task-definition vector-task:latest \
  --desired-count 1

3. Configure model routing to India-hosted endpoints

In openclaw.json, override the model endpoints:

{
  "model_routing": {
    "anthropic": {
      "endpoint": "https://your-india-anthropic-proxy.internal/v1",
      "region": "ap-south-1"
    }
  }
}

If running without external model API access (air-gapped), configure a locally-hosted model via the ollama provider type.

4. Configure database encryption at rest

# Encrypt the SQLite database using SQLCipher
node scripts/migrate-db-encrypted.js \
  --key "$(cat ~/.vault/db-encryption-key)" \
  --input state/vector.db \
  --output state/vector-encrypted.db

Update openclaw.json to use the encrypted database:

{
  "database": {
    "path": "state/vector-encrypted.db",
    "encrypted": true
  }
}

5. Disable all external telemetry

{
  "telemetry": {
    "enabled": false
  }
}

6. Document data flows for compliance

Run the data flow audit:

node scripts/data-flow-audit.js --output reports/data-flows.md

This generates a report of all external API calls, data stored, and retention periods — suitable for including in a government compliance submission.

How to Set Up VECTOR for a New Enterprise Customer

Goal: Deploy a customer-isolated VECTOR instance with customer-specific brand, skills, and compliance configuration.

1. Create the customer directory

mkdir -p customers/acme-corp/{brand,skills,compliance}

2. Create customer brand context

Create customers/acme-corp/brand.yaml:

name: Acme Corporation
primary_color: "#1a3c8f"
secondary_color: "#ffffff"
accent_color: "#e8a020"
font_display: "Helvetica Neue"
font_body: "Georgia"
voice: "Professional, authoritative, sector-specific terminology"
prohibited_terms:
  - "AI-powered"
  - "revolutionary"
  - "disruptive"

3. Create customer compliance rules

Create customers/acme-corp/compliance.yaml:

industry: financial_services
regulations:
  - SOC2_TYPE2
  - PCI_DSS
data_handling:
  pii_allowed: false
  external_api_calls: restricted
  data_residency: us-east-1
content_rules:
  require_disclaimer: true
  disclaimer_text: "This content is for informational purposes only..."

4. Register the customer in openclaw.json

{
  "customers": {
    "acme-corp": {
      "context_dir": "customers/acme-corp",
      "workspace_prefix": "acme",
      "agent_id": "acme-main"
    }
  }
}

5. Validate the customer config

node scripts/validate-customer-config.js --customer acme-corp

6. Run a test task with customer context

# VECTOR will load acme-corp brand and compliance context automatically
echo "Write a LinkedIn post announcing Acme's Q1 results. Customer: acme-corp." | \
  openclaw task --customer acme-corp

How to Rotate Credentials Without Downtime

Goal: Update API keys or tokens without restarting the gateway or interrupting running tasks.

1. Write the new credentials to the auth profiles file

# Edit the secrets file directly — do not use echo or pipes (shell history risk)
nano ~/.openclaw/agents/main/agent/auth-profiles.json

Replace only the changed key value. Keep all other values intact.

2. Signal the gateway to reload credentials

openclaw gateway reload-auth

The gateway reloads the auth profiles file without restarting. In-flight tasks continue with the old credential until their session ends. New sessions use the new credential.

3. Verify the new credential is working

openclaw gateway status --check-auth
# Output: ✓ anthropic: authenticated (new key)

4. Revoke the old credential

Revoke the old API key from the provider's dashboard only after confirming the new key is working. Do not revoke before step 3 passes.

How to Recover from a Gateway Crash

Goal: Restore VECTOR to full operation after an unexpected gateway termination.

1. Check what crashed

tail -50 /var/log/vector-gateway-error.log

Identify whether the crash was caused by:

2. Fix the root cause before restarting

If invalid config:

node scripts/validate-openclaw-config.js
# Fix reported errors, then continue

If disk full:

du -sh ~/.openclaw/workspace/state/
# Archive old audit logs
node scripts/archive-audit-log.js --before 2026-01-01

If port conflict:

lsof -i :18789
# Kill the conflicting process, or change port in openclaw.json

3. Check for in-flight task state

sqlite3 state/vector.db \
  "SELECT id, title, pm, status FROM tickets WHERE status = 'in_progress';"

In-progress tickets from before the crash may need to be reset:

sqlite3 state/vector.db \
  "UPDATE tickets SET status = 'todo' WHERE status = 'in_progress'
   AND updated_at < datetime('now', '-1 hour');"

4. Restart the gateway

openclaw gateway start

5. Verify VECTOR resumes correctly

openclaw gateway status
# Check: active-sprint.json is read and sprint is resumed

VECTOR will read state/active-sprint.json at boot and resume any active sprint. Check the boot output to confirm the correct sprint was resumed.