WolfSuite Workspace · Documentation
Self-host Wolf Workspace
The wolfsdk-workspace command runs a whole workspace on one port: the web app, the API, the room connection and the MCP endpoint for agents. Only clients that present a token from your actors file get in. 1
Start the server
Start the server with a room database, a folder for document files, the Wolf engine, an actors file and a port (--port 0 picks a free one). It prints the room, web app and MCP addresses once it is listening, and stops cleanly on SIGINT or SIGTERM. 1
wolfsdk-workspace serve --db rooms.sqlite --blobs blobs \
--engine ~/.local/bin/wolf --actors actors.json --port 8787
listening ws://127.0.0.1:8787/ws
workspace http://127.0.0.1:8787
mcp http://127.0.0.1:8787/mcpA request without a known token is answered 401, on the web app API, the room connection and /mcp alike. One database is served by one server at a time; a second serve on the same database exits with an error. 1
Add people and agents
actors add writes the actors file. The first call creates it readable only by you (mode 600) and prints the new token once. An agent is added on the seat of a person already in the file, named with --operator. 2 3
wolfsdk-workspace actors add user alice --name Alice --actors actors.json
wolfsdk-workspace actors add agent robot --name Robot --operator alice --actors actors.json- An id the file already holds for that kind is refused, and the file is left as it was. 4
- An operator that is not a person in the file is refused. 3
- A running server picks up a changed actors file without a restart, and keeps the last valid one if the new file is malformed. 5
Give an agent the MCP address and its token, sent as Authorization: Bearer <token>. The tools it gets are listed in the MCP tools reference. 1 6
Seats and the licence limit
seats lists the seats in use, oldest first, as text or JSON, and seats release frees the seat of one person or agent. 7 8
wolfsdk-workspace seats --db rooms.sqlite
wolfsdk-workspace seats release user alice --db rooms.sqliteWithout a licence key the server serves one workspace. A second workspace is refused with LICENSE_LIMIT; more rooms in the first workspace are fine. 9 10
When more seats are in use than the licence allows, the newest seats are freed and the oldest keep working. 11
Started with --read-only-reason and --read-only-upgrade, the server reports the reason on /api/me and refuses every write with HTTP 402 LICENSE_LIMIT, naming the reason and the way to upgrade. 12 13
Back up and restore
backup takes a snapshot of a running workspace and keeps the newest --keep snapshots. restore brings back the same documents, revisions and file bytes, from the newest snapshot or the one you name. 14 15
wolfsdk-workspace backup --db rooms.sqlite --blobs blobs --keep 7 --dir /mnt/backups/rooms
wolfsdk-workspace restore --db new/rooms.sqlite --blobs new/blobs --dir /mnt/backups/rooms- A restore into a place that already holds a workspace stops with the reason and changes nothing. 16
- A backup that finds a document file missing on disk fails and stores no snapshot. 17
GET /api/export returns every document of every room at its current revision, byte for byte, as <room>/<name>, with a manifest last. 18
Evidence
Each numbered reference above points to the test that exercises the statement or to a recorded observation of the hosted service at workspace.wolfsdk.com. Test paths are relative to the WolfSuite repository.
- Test
sdk/web/packages/workspace-cli/test/cli.test.ts: “serve admits only a client with a token on one port for the UI, the API, the socket and MCP, and stops on a signal” - Test
sdk/web/packages/workspace-cli/test/actors-command.test.ts: “makes a missing file with the user, mode 600, and prints the new token once” - Test
sdk/web/packages/workspace-cli/test/actors-command.test.ts: “adds an agent on the seat of a user of the file, and refuses an operator that is not one” - Test
sdk/web/packages/workspace-cli/test/actors-command.test.ts: “refuses an id the file already has for that kind and leaves the file as it was” - Test
sdk/web/packages/workspace-cli/test/cli.test.ts: “serve picks up a changed actors file without a restart, and keeps the last good one when the file is bad” - Test
sdk/web/packages/protocol/test/workspace.test.ts: “eight tools, in order” - Test
sdk/web/packages/workspace-cli/test/cli.test.ts: “lists the seats, oldest first, as text and as JSON” - Test
sdk/web/packages/workspace-cli/test/cli.test.ts: “release frees the seat of one identity, and exits 2 for one that holds none” - Test
sdk/web/packages/server/test/license.test.ts: “a second workspace is refused with LICENSE_LIMIT; more rooms in the first are fine” - Production observation, : In the deployment check, a container started without a licence key answered a second workspace with HTTP 402 LICENSE_LIMIT, and the production container, which holds a key, admitted it. Recorded in
evidence/ltg-ws-stage7-wolf-cloud-hostinger-deploy-20261113.json. - Test
sdk/web/packages/server/test/plan-limits.test.ts: “follows the rule of the licence: the newest seats are freed, the oldest keep working” - Test
sdk/web/packages/workspace-cli/test/cli.test.ts: “serve with the read-only flags reports why on /api/me and refuses a write with 402” - Test
sdk/web/packages/server/test/read-only.test.ts: “is LICENSE_LIMIT with a stable reason, and a message with the reason and the upgrade path verbatim” - Test
sdk/web/packages/workspace-cli/test/backup.test.ts: “backs a running workspace up and restores it: the same documents, revisions and bytes, and a database the server opens” - Test
sdk/web/packages/workspace-cli/test/backup.test.ts: “keeps the newest --keep snapshots, and a restore takes the newest or the one named” - Test
sdk/web/packages/workspace-cli/test/backup.test.ts: “a restore into a place that holds a workspace stops with the reason, and changes nothing” - Test
sdk/web/packages/workspace-cli/test/backup.test.ts: “a backup that finds a blob missing on disk fails and uploads no snapshot” - Test
sdk/web/packages/server/test/export.test.ts: “holds every document of every room as <room>/<name>, at its head, byte for byte, and the manifest last”