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](#evidence-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](#evidence-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/mcp
```

A 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](#evidence-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](#evidence-2) [3](#evidence-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](#evidence-4)
- An operator that is not a person in the file is refused. [3](#evidence-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](#evidence-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](#evidence-1) [6](#evidence-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](#evidence-7) [8](#evidence-8)

```
wolfsdk-workspace seats --db rooms.sqlite
wolfsdk-workspace seats release user alice --db rooms.sqlite
```

Without 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](#evidence-9) [10](#evidence-10)

When more seats are in use than the licence allows, the newest seats are freed and the oldest keep working. [11](#evidence-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](#evidence-12) [13](#evidence-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](#evidence-14) [15](#evidence-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](#evidence-16)
- A backup that finds a document file missing on disk fails and stores no snapshot. [17](#evidence-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-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.

1. 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”
2. 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”
3. 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”
4. 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”
5. 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”
6. Test `sdk/web/packages/protocol/test/workspace.test.ts`: “eight tools, in order”
7. Test `sdk/web/packages/workspace-cli/test/cli.test.ts`: “lists the seats, oldest first, as text and as JSON”
8. 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”
9. Test `sdk/web/packages/server/test/license.test.ts`: “a second workspace is refused with LICENSE_LIMIT; more rooms in the first are fine”
10. Production observation, November 14, 2026: 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`.
11. 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”
12. 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”
13. 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”
14. 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”
15. 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”
16. 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”
17. Test `sdk/web/packages/workspace-cli/test/backup.test.ts`: “a backup that finds a blob missing on disk fails and uploads no snapshot”
18. 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”
