Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stacyide.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Admin Control Plane

This guide covers the operator-facing admin surface added in Phase 5: separate admin authentication, dashboard Operations workflows, owner quota management, diagnostics, and persisted admin audit history.

​
Authentication

StacyVM supports a regular API key and an optional separate admin API key: 
auth:
  enabled: true
  api_key: "sk-client"
  admin_api_key: "sk-admin"
  admin_fallback_enabled: false
  admin_audit_retention: "2160h"
The same values can be supplied with environment variables: 
STACYVM_AUTH_API_KEY=sk-client
STACYVM_AUTH_ADMIN_API_KEY=sk-admin
STACYVM_AUTH_ADMIN_FALLBACK_ENABLED=false
STACYVM_AUTH_ADMIN_AUDIT_RETENTION=2160h
Use X-Admin-API-Key for /api/v1/admin/* requests. If auth.admin_api_key is configured, the regular auth.api_key cannot access admin routes. If no admin key is configured, admin routes fall back to auth.api_key for compatibility unless auth.admin_fallback_enabled is set to false. Production deployments should set auth.admin_fallback_enabled: false and configure a dedicated auth.admin_api_key. Authenticated requests now carry a request-scoped identity with either the api or admin role. Admin identities receive both api:* and admin:* scopes; regular API identities receive api:*. This keeps the current API-key behavior stable while creating a typed authorization boundary for later RBAC and identity-provider integrations. When API-key auth is enabled, admin routes also enforce the admin:* scope at the route layer. This is intentionally redundant with admin-key authentication today and gives future RBAC/OIDC integrations a single policy hook to satisfy. For the production hardening checklist and OIDC/SSO integration plan, see security-governance.

​
Dashboard Setup

Open Settings, enable API key sending, and set:
  • API Key: sent as X-API-Key for regular API requests.
  • Admin API Key: sent as X-Admin-API-Key for operator routes.
Settings are stored in browser local storage. Treat operator browsers as privileged clients and avoid sharing screenshots or profiles that may expose local configuration.

​
Operations Dashboard

The Operations page has three tabs:
TabPurpose
QuotasList, create, update, delete, summarize, and inspect owner quota usage.
DiagnosticsView redacted process, scheduler, rate-limit, build, provider, store, sandbox, and redaction data.
AuditReview, filter, and export persisted admin route access logs.

​
Owner Quotas

Owner quotas are persisted overrides keyed by owner ID. They apply to requests that carry an owner identity through X-User-ID or an owner_id field where supported. Fields:
FieldMeaning
max_sandboxesMaximum active sandboxes for the owner. 0 means no override.
max_ttlMaximum sandbox TTL for the owner, such as 30m or 2h.
max_exec_timeoutMaximum exec timeout for the owner, such as 30s.
Quota changes are admin operations and are recorded in the admin audit log.

​
Diagnostics

Diagnostics are redacted by design. They include operational state useful for support and production checks while avoiding raw API keys, provider secrets, registry credentials, and environment secrets. Use diagnostics during incidents to confirm:
  • Store health and latency.
  • Provider health and capabilities.
  • Scheduler and spawn queue state.
  • Rate-limit state.
  • Sandbox count by state/provider.
  • Quota coverage summary.

​
Admin Audit

Admin route access is persisted in SQLite in the admin_audit_logs table. Records include:
  • Actor from X-User-ID, or admin when no actor header is supplied.
  • When X-User-ID is missing on an authenticated admin request, the actor falls back to the authenticated role and key header, such as admin:X-Admin-API-Key.
  • HTTP method and path.
  • HTTP status and request duration.
  • Request ID.
  • Client address and user agent.
  • Timestamp.
The Audit tab supports filters for actor, method, status, and path substring. It can export the current filtered view as CSV. The API equivalent is: 
curl \
  -H "X-Admin-API-Key: $STACYVM_ADMIN_API_KEY" \
  "https://stacyvm.example.com/api/v1/admin/audit?actor=operator-a&method=PUT&format=csv"

​
Storage And Retention

Audit logs live in the main SQLite database. They are included in normal database backups. Native retention is controlled by auth.admin_audit_retention. Set the value to a Go duration such as 720h for 30 days or 2160h for 90 days. 0s disables native pruning. Pruning runs after successful admin audit writes, so records older than the retention window are removed as operators use the admin control plane.