Important
This repository is archived. StateDock Docker has been merged into
statedock-local: the same program now runs on
your computer, on a Linux server (one-line systemd installer) and in Docker. New releases, fixes
and the Docker image ghcr.io/statedock/statedock are published there only.
Your data is compatible as-is: same statedock.db, same schema.
Stay on Docker
docker compose down(stops the old container and flushes the SQLite WAL).- Back up:
cp -a ./data ./data.bak. - In
compose.yaml, change thestatedockservice:Caddy can stay as it is (stillstatedock: image: ghcr.io/statedock/statedock:latest # replaces image/build environment: - PUBLIC_BASE_URL=https://your-domain # your public address # - STATEDOCK_AGENT_TOKEN=... # keep it if you had one volumes: - ./data:/data # unchanged
reverse_proxy statedock:3000). docker compose up -d.- The web UI now requires sign-in. Use your
STATEDOCK_AGENT_TOKEN, or if you never set one:docker compose exec statedock node dist/index.js token --no-open. - Agents: keep the same MCP URL and send
Authorization: Bearer <token>.
Move to a plain Linux service (no Docker)
docker compose down
curl -fsSL https://raw.githubusercontent.com/statedock/statedock-local/main/scripts/install.sh \
| sudo bash -s -- --public-url https://your-domain
sudo systemctl stop statedock
sudo cp ./data/statedock.db /var/lib/statedock/statedock.db
sudo chown statedock: /var/lib/statedock/statedock.db
sudo systemctl start statedock
sudo statedock tokenFull guide: statedock-local/docs/server.md
Previous README (for reference only)
A shared workspace for people and coding agents to track project goals, tasks, and outcomes.
One container. Built-in SQLite. No external database. No mandatory email service.
Your tasks, projects, and agent handoffs — under your control.
Run on any server, VPS, or local machine with Docker installed:
docker run -d \
--name statedock \
--restart unless-stopped \
-p 3000:3000 \
-v ~/statedock-data:/data \
statedock/statedock:latestWhen started for the first time, StateDock generates a high-entropy one-time Setup Token. Check your container logs:
docker logs statedockYou will see the activation output:
======================================================================
[StateDock Setup Required] Initial Setup Security Token:
Setup Token: sd_setup_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Setup URL: http://<YOUR_IP>:3000/setup?token=sd_setup_...
Once configured, this setup endpoint will be permanently disabled.
======================================================================
Open the activation link in your browser to create your administrator account. Once setup is complete, the /setup endpoint is permanently closed to prevent unauthorized public registrations.
Ideal for servers with a domain name. Caddy automatically provisions and renews Let's Encrypt TLS certificates:
-
Clone or download this repository:
git clone https://github.com/statedock/statedock-docker.git cd statedock-docker -
Edit
caddy/Caddyfile, replacingdock.example.comwith your actual domain:dock.example.com { reverse_proxy statedock:3000 }
-
Start services:
docker compose up -d
Note: If you use an existing reverse proxy (e.g. Nginx, 1Panel, or Traefik), you can use Method 1 and proxy traffic to
localhost:3000.
StateDock provides a standard Streamable HTTP Model Context Protocol (MCP) endpoint:
- Endpoint URL:
http://<YOUR_IP>:3000/mcp(orhttps://dock.example.com/mcp) - Supported Clients: Cursor, VS Code, Codex, Claude Desktop, Antigravity, etc.
{
"mcpServers": {
"statedock": {
"url": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer YOUR_AGENT_TOKEN"
}
}
}
}Once connected, agents can call get_instance_info, resume_project, claim_next_task, and submit_handoff to collaborate on projects across coding sessions.
The separate StateDock plugins repository contains MIT-licensed shared Skills for saving plans, restoring task context, and recording progress. The published packages currently default to the hosted StateDock service at https://statedock.dev/mcp. To use them with this Docker instance, configure the agent host to connect to the endpoint above and follow the platform-specific setup; that self-hosted plugin configuration has not been verified as part of the published packages.
- Codex: installable from the GitHub repository as a local marketplace.
- DeepSeek Harness:
@statedock/dsh-pluginis published for Harness0.2.0-rc.2; see the official community showcase. - ChatGPT app: submitted to OpenAI for review; approval is pending.
- Cursor: Marketplace submission materials are being prepared; installation and approval are not yet verified.
The plugins only record and restore project state. They do not run task code or schedule agents. Plugin code is MIT-licensed; this Docker edition remains AGPL-3.0-only.
All state is stored inside the mounted /data directory:
/data/statedock.db: Primary SQLite database (WAL mode enabled by default)/data/attachments/: Uploaded task screenshots and attachments/data/backups/: Database snapshot backups
Because SQLite operates in WAL mode, avoid copying raw .db files while the process is actively running. StateDock exposes an atomic hot backup endpoint:
curl -X POST http://localhost:3000/api/admin/backupThis triggers SQLite VACUUM INTO and outputs a clean, transactionally consistent snapshot in /data/backups/statedock-backup-YYYY-MM-DDTHH-mm-ss.db.
To migrate to another machine:
- Stop the container:
docker stop statedock - Archive the mounted directory:
tar -czvf statedock-data.tar.gz ~/statedock-data - Copy the archive to your target machine, extract it, and start the container with the same volume mount.
Requirements: Node.js 22+ and pnpm 9.15.4.
pnpm install
pnpm build
pnpm test
pnpm devStateDock Docker is licensed under AGPL-3.0-only.
Third-party dependency licenses are listed in THIRD_PARTY_NOTICES.md.