The handbook
TroubleshootingLocal developmentDeploymentProvision a new clientStandalone deploymentUpgradesArchitecture
Operate

Deployment

The console is a Next.js static-export bundle deployed to AWS Amplify Hosting at os.aca.so. No Node runtime is required in production.

Required AcasoOS env vars

The console talks to one AcasoOS instance per connection. That instance must allow the console's origin and expose the v1 admin surface.

VarProduction defaultPurpose
ACASO_CONSOLE_ORIGINSemptyStrict CORS allow-list. https://os.aca.so for the hosted console.
ACASO_SESSION_TTL_SECONDS28800 (8h)TTL on session keys minted by /v1/auth/session.
ACASO_SESSION_CLEANUP_GRACE_DAYS7Days after expires_at before the cleanup job hard-deletes a session row.

See Reference: Environment variables for the full list and defaults.

Warning: Wildcard * in ACASO_CONSOLE_ORIGINS is rejected at AcasoOS startup. There is no escape hatch by design.

Amplify build

packages/web/amplify.yml defines the build:

yaml
version: 1
applications:
  - appRoot: packages/web
    frontend:
      phases:
        preBuild:
          commands:
            - corepack enable
            - corepack prepare pnpm@9.15.4 --activate
            - pnpm install --frozen-lockfile
        build:
          commands:
            - pnpm --filter @acaso/web build
      artifacts:
        baseDirectory: out
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - ~/.local/share/pnpm/store/**/*

In the Amplify console:

  • Set "monorepo project root" to packages/web.
  • Connect the repo and pick the branch.
  • Leave build settings on the inferred values; the amplify.yml overrides what matters.

DNS

CNAME os.aca.so to the Amplify-hosted domain. Amplify handles TLS via its built-in ACM integration.

Smoke check the deploy

After Amplify reports the deployment as live:

  1. Open https://os.aca.so. You land on /connect.
  2. Submit a connection against a real AcasoOS instance whose ACASO_CONSOLE_ORIGINS includes https://os.aca.so.
  3. Verify the session exchange succeeds and you land on /agents.
  4. Inspect DevTools → Application → Storage. Confirm no long-lived key is present in any tier.

Failure at step 3 with a CORS error means the AcasoOS instance does not list https://os.aca.so in ACASO_CONSOLE_ORIGINS. See Troubleshooting.

Static export properties

  • The bundle is a tree of HTML + JS + CSS. No server runtime. No environment variables baked at deploy time.
  • CDN-cacheable on Amplify's edge. The initial route (/connect) should serve under 200ms TTFB from a regionally-close edge after warm.
  • All API endpoints (URL, key) are configured at runtime via the Connect form. The same bundle deploys to multiple environments.

Self-hosted future

A future spec covers shipping the console bundle inside the AcasoOS Docker image so customers can serve it at the same origin as their AcasoOS API. That removes the CORS step entirely. v1 is acaso-hosted only.

PreviousOperateLocal developmentNext OperateProvision a new client