Gateway

Authenticated HTTP gateway for per-user pi runs.

Owns

• bearer JWT auth for portal callers
• authenticated user -> workspace/session routing
• run REST + SSE API
• sandboxed pi --mode rpc execution via systemd-run
• workspace file, archive, sync, and image-generation APIs
• loopback-only internal provider proxy

Core boundary

The caller never chooses a cwd or session id.

The gateway derives everything from authenticated user and always targets that user's editable workspace, never any portal-managed live checkout.

Main surfaces

Public API:

• /health
• /session, /context
• /runs, /runs/:runId, /runs/:runId/events, /runs/:runId/cancel
• /workspace, /workspace/archive, /workspace/sync
• /workspace/files, /workspace/files/content
• /workspace/images/generate

Internal API:

• loopback-only provider listener used by the sandbox runtime

Runtime rules

• one active run per user; no queue
• each user gets one editable workspace and one stable session file
• sandbox mounts only the authenticated workspace/session plus trusted runtime files
• upstream model credentials stay outside the sandbox
• workspace sync plus terminal commit/push stay scoped to the editable workspace
• preview/live site serving comes from built dist/ output, but live checkouts stay outside gateway routing

Key directories

• src/ — app construction, route modules, runtime, workspace, and provider logic
• trusted/ — trusted extension, sandbox instructions, and build-site
• docs/ — stable package-level docs
• scripts/ — migration and packaging helpers

Environment groups

• network/runtime: HOST, PORT, REQUEST_TIMEOUT_MS, WORKSPACE_FINALIZATION_TIMEOUT_MS, MAX_UPLOAD_MB
• auth/routing: JWT_SHARED_SECRET, BASE_WORKDIR, SESSION_DIR
• pi/provider: PI_BIN, INTERNAL_PROVIDER_HOST, INTERNAL_PROVIDER_PORT, PI_GATEWAY_EXTENSION_PATH, PI_GATEWAY_CODEX_AUTH_FILE, PI_GATEWAY_CODEX_UPSTREAM_BASE_URL, PI_DISABLE_CONTEXT_FILES, SANDBOX_INTERNET_ENABLED, PI_SANDBOX_AGENTS_PATH
• image generation: OPENAI_API_KEY, OPENAI_IMAGE_MODEL, OPENAI_IMAGE_SIZE, OPENAI_RESPONSES_MODEL
• workspace Git + Gitea sync: WORKSPACE_GIT_INIT_ENABLED, WORKSPACE_GIT_DEFAULT_BRANCH, WORKSPACE_GIT_INITIAL_COMMIT_MESSAGE, WORKSPACE_REMOTE_MODE, WORKSPACE_AUTO_COMMIT_AUTHOR_NAME, WORKSPACE_AUTO_COMMIT_AUTHOR_EMAIL, WORKSPACE_AUTO_COMMIT_MESSAGE_PREFIX, GITEA_BASE_URL, GITEA_WORKSPACE_REPO_NAME, GITEA_SYNC_SERVICE_USERNAME, GITEA_SYNC_SERVICE_TOKEN

Gateway startup validates mandatory JWT and supported Gitea sync config before listening. Temporary Gitea outages are still handled at request time; only missing, invalid, or placeholder config blocks startup.

Current Git hosting support is Gitea-only and the setup is manual:

• GITEA_SYNC_SERVICE_USERNAME and GITEA_SYNC_SERVICE_TOKEN must belong to a pre-created Gitea account used for workspace Git fetch/push
• that sync account is intended to stay separate from the portal's admin credential so the gateway does not hold the admin token
• portal provisioning grants this sync account collaborator access on each user workspace repo

Key defaults in code:

• workspaces: ../.local/gateway/workspaces
• sessions: ../.local/gateway/sessions
• internal provider host: 127.0.0.1 only
• sandbox internet: disabled unless explicitly enabled
• post-run workspace finalization timeout: 120000ms
• image model: gpt-image-2

Local commands

npm run dev
npm run typecheck
npm run build
npm start

Package docs

• docs/overview.md — scope and guarantees
• docs/api-and-media.md — public API and workspace-file rules
• docs/auth-routing-and-concurrency.md — identity, routing, and lock model
• docs/pi-runtime.md — sandbox runtime contract
• docs/platform-config-and-testing.md — config defaults and testing priorities
• docs/image-generation.md — image-generation feature note

Related packages

• browser-facing caller: ../portal/README.md
• deployment/operator docs: ../cli/README.md and ../cli/docs/