Operate

Update

git pull
./setup.sh
docker compose up --detach --wait --build

./setup.sh keeps every value .env has and rebuilds the runtime image so a change under runtime/ reaches the next sandbox. --build rebuilds the orchestrator image from the checkout. Boot applies new migrations before it listens (Orchestrator).

Back up

Everything the box knows is STATE_ROOT and .env. PostgreSQL holds notes, records, memory, scripts, runs, and every credential, encrypted; workspaces/ holds what agents wrote to disk and attachments/ the uploaded files. Copy STATE_ROOT with the stack stopped (docker compose stop), or dump the database while it runs:

docker compose exec -T postgres pg_dump -U agent_platform -Fc agent_platform > guilds.dump

A backup without .env cannot decrypt its credentials.

Restore

A copy of STATE_ROOT goes back in place with the stack stopped, with the .env it was made under, and docker compose up --detach --wait starts from it. A dump loads into the running database with the orchestrator stopped:

docker compose stop orchestrator
docker compose exec -T postgres pg_restore -U agent_platform -d agent_platform --clean --if-exists < guilds.dump
docker compose start orchestrator

Logs

The orchestrator writes one JSON line per event to stdout, which Docker keeps as json-file logs (five files of 10 MB):

docker compose logs --follow orchestrator

Each line carries timestamp, level, run_id, guild_id, agent_id, operation, error_type, message, and traceback, and when they apply source, request_id, session_id, path, method, and status. Warnings and errors are also written to stderr as one readable line. Every value of an environment variable whose name ends in API_KEY, SECRET, TOKEN, PASSWORD, or PASSWD is replaced by [REDACTED:<name>] before a line is written. Every API call from the operator app carries that tab's X-Request-Id, which appears as request_id, and the app reports its own uncaught errors and failed calls to the server (source: frontend), so one id lines up what the operator saw with what the server did.

Boot logs listening once the server accepts requests, and sentry enabled or sentry disabled. With SENTRY_DSN set, errors and traces go to Sentry under SENTRY_ENVIRONMENT, sampled at SENTRY_TRACES_SAMPLE_RATE; user information, cookies, request bodies, model inputs and outputs, and query data are not sent.

GET /health answers {"status":"ok"} after a database ping, for a monitor outside the box.

When it fails

Message	Cause
run ./setup.sh first, which writes it into .env	docker compose found no .env, or one without STATE_ROOT, SECRETS_MASTER_KEY, POSTGRES_PASSWORD, or OPENSANDBOX_API_KEY
STATE_ROOT must be an absolute path	.env names a relative path; OpenSandbox mounts workspaces by the absolute one
… already holds a database, and .env has no …	./setup.sh would generate a secret over a database created with another one. Put that database's values into .env, or point STATE_ROOT at an empty directory
SECRETS_MASTER_KEY is the all-zero development key: set 32 random bytes	The orchestrator refuses the development key outside the development stack (Security register, SEC-14)
SECRETS_MASTER_KEY must be 32 bytes (base64 or hex)	The key is not 32 bytes
AUTH_MODE must be compat-cookie, trusted-header	.env names a mode core does not have
TRUSTED_PROXY_SECRET is required when AUTH_MODE=trusted-header, and the same for PUBLIC_BASE_URL and OPERATOR_EMAIL	The proxy mode is missing one of its three settings (Remote access)
OPERATOR_EMAIL is another user's email	A user other than the box's first already holds that address
A banner above every page says No model key yet	Neither the organisation nor the server has any model key. Connect one under Settings, Model keys, or set OPENROUTER_API_KEY or DEEPINFRA_API_KEY and restart (Install)
A run ends with OPENROUTER_API_KEY is not set (or DEEPINFRA_API_KEY)	Neither the organisation nor the server has a key for that model's provider (Configure)
A run ends with a … key is not connected	A coding agent runs a model that takes an organisation key only, and the organisation has none under Settings, Model keys
Stored credentials fail to decrypt after a restore	The restore runs under a different SECRETS_MASTER_KEY than the one the data was written with

The orchestrator container restarts on its own (restart: unless-stopped); a setting it refuses shows in its log on every attempt.