OpenWork Hosted Runtime Storage + Environment Contract
Version: 1.0
Date: 2026-03-07
Owner: Platform Engineering
Related: PLT-1072, knowledge/engineering/openwork-platform-integration/openwork-platform-integration-plan.md
1) Purpose
Define the deployment contract for the hosted OpenWork runtime. Platform presents work.brainforge.ai as the default user URL; labs.brainforge.ai is legacy or environment-specific. The current app source of truth lives in brainforge-work.
This contract covers:
- persistent storage layout (
/dataand derived paths), - required environment variables and token handling,
- where each value is sourced (1Password vs Railway config),
- deployment/backup/recovery constraints.
2) Canonical secret source
Decision: 1Password is the canonical secret store for hosted OpenWork credentials.
Runtime injection: Railway environment variables.
Pattern:
- Generate/update secret values.
- Store canonical value in 1Password (
Brainforge AI Teamvault). - Copy into Railway service/environment variables for runtime use.
Never commit secrets into the repo.
3) Runtime storage contract
Hosted OpenWork runs on Railway today, which supports a single mounted volume per service. The
accepted first-release contract is therefore a single durable /data mount with the workspace
nested beneath it.
The /data mount must survive restarts/redeployments.
3.1 Required persistent paths
| Path | Purpose | Persistence requirement | Notes |
|---|---|---|---|
/data/workspace | Primary OpenWork workspace root (OPENWORK_WORKSPACE) | Required durable volume | Includes .opencode/ project state and user files. |
/data/openwork-orchestrator | Orchestrator data dir (OPENWORK_DATA_DIR) | Required durable volume | Includes orchestrator state file and server audit logs (via OPENWORK_DATA_DIR). |
/data/sidecars | Downloaded sidecar cache (OPENWORK_SIDECAR_DIR) | Required durable volume | Avoids repeated sidecar downloads on every deploy. |
/data/openwork-server/server.json | Optional persisted server config (OPENWORK_SERVER_CONFIG) | Required if using file-based server config | Prevents drift to ephemeral ~/.config/openwork/server.json. |
/data/openwork-server/tokens.json | Scoped token store (OPENWORK_TOKEN_STORE) | Required if /tokens API is used | Keeps owner/collaborator/viewer tokens durable across restarts. |
3.2 Storage constraints
- The service must not rely on
~/.config/openwork/*or other container-home paths for critical runtime state. OPENWORK_DATA_DIRandOPENWORK_SIDECAR_DIRmust resolve under/data.OPENWORK_WORKSPACEmust resolve under/data/workspace.- Because Railway exposes a single durable mount, workspace growth and runtime metadata writes share the same underlying volume. Capacity planning should treat them together for the first release.
4) Environment variable contract
4.1 Required for first hosted release
| Variable | Secret | Source of truth | Runtime location | Required value/shape |
|---|---|---|---|---|
OPENWORK_WORKSPACE | No | Railway config | Service env | /data/workspace |
OPENWORK_DATA_DIR | No | Railway config | Service env | /data/openwork-orchestrator |
OPENWORK_SIDECAR_DIR | No | Railway config | Service env | /data/sidecars |
OPENWORK_TOKEN | Yes | 1Password → Railway | Service env | Long random bearer token for client auth |
OPENWORK_HOST_TOKEN | Yes | 1Password → Railway | Service env | Long random bearer token for host/owner actions |
4.2 Required for durable server metadata
| Variable | Secret | Source of truth | Runtime location | Required value/shape |
|---|---|---|---|---|
OPENWORK_SERVER_CONFIG | No | Railway config | Service env | /data/openwork-server/server.json |
OPENWORK_TOKEN_STORE | No | Railway config | Service env | /data/openwork-server/tokens.json |
4.3 Conditional/hardening vars (set when applicable)
| Variable | Secret | When to set | Notes |
|---|---|---|---|
OPENWORK_APPROVAL_MODE | No | Explicitly set per environment | Use manual for hosted Labs unless an approval policy change is approved. |
OPENWORK_APPROVAL_TIMEOUT_MS | No | If non-default timeout needed | Default is 30000. |
OPENWORK_CORS_ORIGINS | No | If tightening from wildcard | Prefer explicit origins once ingress is finalized. |
OPENWORK_SIDECAR_SOURCE | No | If pinning resolution strategy | Allowed: auto, bundled, downloaded, external. |
OPENWORK_OPENCODE_USERNAME | Yes | If OpenCode auth is enabled | Store in 1Password, inject via Railway. |
OPENWORK_OPENCODE_PASSWORD | Yes | If OpenCode auth is enabled | Store in 1Password, inject via Railway. |
5) Human-owned setup steps (ops checklist)
-
Provision storage
- Create/attach a persistent volume at
/data. - Confirm
/data/workspace,/data/openwork-orchestrator, and/data/sidecarsare writable by the runtime user.
- Create/attach a persistent volume at
-
Create secrets
- Generate strong random values for
OPENWORK_TOKENandOPENWORK_HOST_TOKEN. - Store canonical values in 1Password (
Brainforge AI Teamvault).
- Generate strong random values for
-
Configure Railway env
- Set all required variables from Sections 4.1 and 4.2.
- Copy secret values from 1Password into Railway env variables.
-
Set sidecar strategy
- Choose and set
OPENWORK_SIDECAR_SOURCEif not usingauto. - Verify outbound access to sidecar artifact source if
downloadedis used.
- Choose and set
-
Pre-launch verification
- Deploy service.
- Confirm
GET /healthsucceeds. - Confirm
GET /uisucceeds. - Restart/redeploy once, then verify data still exists under
/data/workspaceand/data/openwork-orchestrator.
6) Backup + recovery constraints
6.1 Backup requirements
- Backup the persistent
/datamount on a regular schedule. - Include:
- workspace contents (
/data/workspace), - orchestrator/runtime metadata (
/data/openwork-orchestrator), - server config + token store paths under
/data/openwork-server(if used).
- workspace contents (
- Sidecar cache at
/data/sidecarsis recoverable by re-download, but backing it up reduces cold-start time after restore.
6.2 Recovery requirements
- Restore
/datafrom a compatible snapshot. - After restore:
- verify
GET /health, - verify
GET /ui, - verify workspace visibility and session operations,
- verify auth with current
OPENWORK_TOKENandOPENWORK_HOST_TOKEN.
- verify
6.3 Explicit non-goals in this contract
- Production credential rotation policy details.
- Desktop-only path conventions.
- Platform/OpenWork same-origin auth bridging design.
7) Follow-on ticket dependencies
Deployment/runbook tickets implementing hosted OpenWork should reference this contract directly and avoid redefining:
- mount paths,
- env var names,
- secret ownership.
If runtime behavior changes (new required env vars, new durable paths), update this file first.