Docker Deployment

Deploy InnoClaw with Docker in under 2 minutes.

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• At least one AI API key (OpenAI, Anthropic, etc.)

Quick Start

git clone https://github.com/SpectrAI-Initiative/InnoClaw.git
cd InnoClaw
cp .env.production.example .env.production.local
# Edit .env.production.local — set at least one API key
docker compose up -d

Open http://localhost:3000.

Configuration

Environment Variables

Edit .env.production.local before starting. Key variables:

Variable	Required	Description
WORKSPACE_ROOTS	Yes	Comma-separated paths inside the container (e.g., /research)
OPENAI_API_KEY	At least one AI key	OpenAI API key
ANTHROPIC_API_KEY		Anthropic API key
DATABASE_URL	No	SQLite path (default: ./data/innoclaw.db)
AUTH_MODE	No	Set to disabled only for trusted deployments that should bypass registration/login
AUTH_SINGLE_ADMIN	No	Set to true to enforce one bootstrapped administrator and ordinary-user registration
AUTH_COOKIE_SECURE	No	Defaults to true in production; use false only for a temporary plain-HTTP rollout
AUTH_SECRET	Production	Long random value used to sign session cookies
LLM_PROVIDER	No	Default provider (openai, anthropic, etc.)
OPENAI_REASONING_EFFORT	No	OpenAI reasoning effort; ultra is normalized to xhigh

See .env.production.example for the full list.

To run without application-level registration or login, set AUTH_MODE=disabled in .env.production.local before starting the container. Anyone who can reach the service gets admin-level access, so use it only behind trusted network access or another access-control layer.

Bootstrap a Single Administrator

For a public multi-user deployment, configure at least:

AUTH_MODE=local
AUTH_SINGLE_ADMIN=true
AUTH_COOKIE_SECURE=true
AUTH_SECRET=replace-with-a-long-random-secret
WORKSPACE_ROOTS=/research

Start the container so migrations complete, then create the sole administrator with a password supplied only through standard input:

umask 077
openssl rand -base64 32 > /tmp/innoclaw-admin-password
docker compose exec -T innoclaw node /app/admin-cli/scripts/bootstrap-admin.js \
  --email admin@example.com --name Administrator \
  < /tmp/innoclaw-admin-password

Store the generated password in your password manager and securely remove the temporary file after delivery. Re-running the same command is idempotent and does not rotate an existing administrator password. Bootstrap must finish before public registration becomes available. Registered users are always ordinary users and cannot promote themselves or another account.

For a temporary plain-HTTP rollout, set AUTH_COOKIE_SECURE=false so browsers can send the session cookie. This does not encrypt credentials or traffic. Move to HTTPS and restore AUTH_COOKIE_SECURE=true as soon as possible.

OpenAI-Compatible Reasoning

OPENAI_REASONING_EFFORT accepts none, minimal, low, medium, high, and xhigh. The operator-friendly value ultra is normalized to xhigh before OpenAI language-model calls. Omit the variable to retain the provider default. The setting does not affect embeddings or non-OpenAI providers; verify that a custom OpenAI-compatible endpoint supports the normalized value.

Volumes

Container Path	Purpose	Compose Default
/app/data	SQLite database, HF datasets, embeddings	Named volume innoclaw-data
/research	Your workspace files	HOST_WORKSPACE_PATH env var or ./workspace

In single-administrator mode, an ordinary user's effective root is provisioned lazily at /research/users/<immutable-user-id> with private permissions. Users can create and operate only their own workspaces. The administrator can view and manage workspace records across the full /research operator root.

To expose multiple workspace directories, add more volume mounts in docker-compose.yml and update WORKSPACE_ROOTS accordingly:

volumes:
  - innoclaw-data:/app/data
  - /home/user/papers:/papers
  - /home/user/code:/code

WORKSPACE_ROOTS=/papers,/code

Port

Default: 3000. Change in docker-compose.yml:

ports:
  - "8080:3000"

Reverse Proxy

InnoClaw works behind any reverse proxy. Examples:

Nginx

limit_req_zone $binary_remote_addr zone=innoclaw_login:10m rate=10r/m;
limit_req_zone $binary_remote_addr zone=innoclaw_register:10m rate=1r/m;

server {
    listen 443 ssl;
    server_name innoclaw.example.com;

    ssl_certificate     /etc/ssl/certs/innoclaw.pem;
    ssl_certificate_key /etc/ssl/private/innoclaw.key;

    location = /api/auth/login {
        limit_req zone=innoclaw_login burst=10 nodelay;
        limit_req_status 429;
        proxy_pass http://localhost:3000;
        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 $scheme;
    }

    location = /api/auth/register {
        limit_req zone=innoclaw_register burst=2 nodelay;
        limit_req_status 429;
        proxy_pass http://localhost:3000;
        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 $scheme;
    }

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 $scheme;
    }
}

Caddy

innoclaw.example.com {
    reverse_proxy localhost:3000
}

Caddy handles TLS automatically.

Persistent Data & Backups

All persistent state lives in the innoclaw-data volume:

• innoclaw.db — SQLite database (notebooks, chat history, settings)
• hf-datasets/ — cached HuggingFace datasets

Back up the database while the service is running:

docker compose exec -T innoclaw node -e \
  'const Database=require("better-sqlite3");const db=new Database("/app/data/innoclaw.db");db.backup("/app/data/innoclaw.db.backup").then(()=>db.close())'
docker cp "$(docker compose ps -q innoclaw):/app/data/innoclaw.db.backup" ./backup.db

The online backup API includes committed WAL state. Also back up the root-readable environment file and reverse-proxy configuration, and retain the previous image until login, workspace isolation, and model inference smoke tests pass.

Upgrading

git pull
docker compose build
docker compose up -d

Database migrations run automatically on container startup — no manual steps needed. The canonical workspace-path preflight runs before the unique path index. If two legacy rows resolve to the same filesystem path, startup stops and reports the colliding workspace IDs instead of deleting or reassigning data.

Build from Scratch

docker build -t innoclaw .
docker run -d \
  --name innoclaw \
  -p 3000:3000 \
  --env-file .env.production.local \
  -v innoclaw-data:/app/data \
  -v /path/to/your/research:/research \
  innoclaw

Troubleshooting

Issue	Fix
/app/data is not writable	Ensure the Docker volume is mounted and the container user has write access
workspace root missing	Mount your host directory in docker-compose.yml and match WORKSPACE_ROOTS
no AI API key detected	Edit .env.production.local and set at least one valid API key
drizzle-kit migrate failed	Usually harmless on first run; check that /app/data is writable
Container exits immediately	Run docker compose logs innoclaw to see the startup error