Run Adapt
Self-host
A self-hosted Adapt is one Node.js service and a PostgreSQL database that you run on your own infrastructure, with the providers you choose.
Adapt is MIT-licensed. Its source is published on January 12, 2027; until then, Adapt is available as a managed Adapt Cloud workspace by request at adapt.com/early-access. The steps below are how the published source runs.
No Adapt-run service is required. Models, sandboxes, knowledge, and integrations are connections you add in the app, and each one calls only the provider you configured. With a local model and local Docker sandboxes, Adapt can run without OpenAI, Anthropic, Modal, or Adapt Platform.
Requirements
- Node.js 24 or later, with Corepack for pnpm.
- PostgreSQL. The included Compose file uses PostgreSQL 17.
- A public HTTPS address if you want Slack, GitHub, email, or text messages to reach Adapt, or coding agents to connect over MCP. Providers can't deliver to
localhostor plain HTTP. - Disk or a Google Cloud Storage bucket for uploaded and generated files.
One process serves the web app and the API from one origin, and runs the background workers that execute agent runs and deliver replies.
Run with Docker Compose
The repository includes a Compose file with PostgreSQL, a migration job, and the app. Create .env with fresh keys, then start it:
corepack pnpm env:init
# In .env, set APP_URL=http://localhost:8080
# and POSTGRES_PASSWORD to a strong URL-safe value.
docker compose --profile app up --build -d
Open http://localhost:8080. Migrations finish before the app starts, the database persists in the postgres volume, and the app runs as a non-root user. Compose publishes the app and database on 127.0.0.1 only; put a reverse proxy in front for other machines.
env:init writes AUTH_SECRET and ENCRYPTION_KEY as independent random values and won't overwrite an existing .env.
Run the Node service
Build, install production dependencies, apply migrations, then start:
corepack pnpm install --frozen-lockfile
corepack pnpm build
corepack pnpm --dir dist/runtime install --prod --frozen-lockfile --ignore-scripts
corepack pnpm db:migrate
NODE_ENV=production corepack pnpm start
The build stages a production copy in dist/runtime; the Docker image contains the same copy. In production the server listens on all interfaces.
Behind a reverse proxy, terminate HTTPS at the proxy, preserve cookies, and turn off response buffering so long-lived event streams reach the browser. /health reports liveness and /ready checks the database.
Configure
Adapt reads these environment variables at startup and refuses to start if one is invalid.
DATABASE_URL=postgres://user:password@host:5432/adapt # required
APP_URL=https://adapt.example.com # public origin; default http://localhost:5173
AUTH_SECRET=... # required, at least 32 characters
ENCRYPTION_KEY=... # required, base64 of exactly 32 bytes
PORT=3001 # default 3001
TRUSTED_PROXIES= # comma-separated proxy IPs or CIDRs; default empty
Generate each secret independently, for example with openssl rand -base64 32.
APP_URL: the address people open, including a nonstandard port. Sign-in, CSRF checks, and every surface's Request URL use it.TRUSTED_PROXIES: the proxies allowed to setX-Forwarded-For. Empty means the socket address identifies the client. Behind a proxy, list every proxy hop, never client networks, so clients don't share a sign-in rate-limit bucket. Write IPv4-mapped ranges as IPv4 CIDRs; an invalid entry stops startup.ENABLE_DOCKER_SANDBOX:trueorfalse, defaultfalse. Allows the local Docker sandbox provider. The Compose app container has no Docker access; run Adapt on a dedicated Docker host to use it, or choose another sandbox provider.PLATFORM_URL: the Adapt Platform API used by Adapt sandbox connections. Defaults tohttps://platform.adapt.comwhen unset or empty.ASSETS_DIR: where files are stored on disk. Defaults to.assetsat the repository root locally and/app/.assetsin Docker. Keep it outsidedist/runtime.GCS_BUCKET: an existing Google Cloud Storage bucket name, withoutgs://. When set, files go there instead ofASSETS_DIR. Adapt authenticates with Application Default Credentials, needs read, write, list, and delete on the bucket, and doesn't create the bucket or move existing files.WEB_DIST: optional absolute path to the built web assets.GITHUB_TOKEN: optional. Raises GitHub's rate limit for reading public repositories, such as when importing skills.
Keep the encryption key safe
ENCRYPTION_KEY encrypts every saved credential: connection API keys and tokens, workspace secrets, and the Google sign-in client secret. Back up PostgreSQL and the key together. Without the key, saved credentials can't be read. Replacing the key doesn't re-encrypt anything: before rotating it, re-encrypt existing records deliberately or plan to enter the credentials again. Use the same AUTH_SECRET and ENCRYPTION_KEY on every replica, and keep the two different.
Sign-in and accounts
An install has one workspace. The first account created by password sign-up is the installer's: it creates the workspace and becomes its Owner. Sign-up then closes, and people join through an invitation link from Settings → Members, valid for 48 hours for one email address. Adapt doesn't send email for invitations, password recovery, or verification; share the link yourself, and protect the install with your own network or identity controls where you need more.
The workspace's company domain is set at install from the installer's email domain. A free or disposable email provider, such as gmail.com, sets no domain. With a company domain, owners and admins can turn on Google sign-in in Settings → Authentication:
- In Google Cloud, set the OAuth consent screen to Internal.
- Create a Web application client with the redirect URI
<APP_URL>/api/auth/callback/google. - Paste its client ID and secret.
Only Google accounts on the company domain can sign in with Google, and anyone on that domain who does joins the workspace as a member. Once Google sign-in is on, password sign-in can be turned off; then only the installer's account keeps its password as a fallback, and pending invitations are canceled. The app never changes the domain after install.
Tracing
Set OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT to export OpenTelemetry traces over OTLP HTTP. Without one, tracing is off.
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
TRACE_CONTENT_WORKSPACES= # comma-separated workspace IDs
Each run is an adapt.run span with model calls and tool calls inside it. Traces carry metadata only: models, token usage, timings, tool names, and error types. Prompts, outputs, and tool arguments and results are exported only for workspaces listed in TRACE_CONTENT_WORKSPACES. The standard OTEL_EXPORTER_OTLP_HEADERS and OTEL_SERVICE_NAME variables apply.
Run more than one replica
Point every replica at the same database, with identical AUTH_SECRET and ENCRYPTION_KEY. Workers claim jobs from PostgreSQL, so any number of replicas can run side by side. Each process runs up to 16 agent runs at once, and each conversation has at most one active run.
Scheduled automations use pg-boss, which creates and migrates a pgboss schema in the same database at startup; the database role must be able to manage it. Back up both schemas. At least one replica must be running for schedules to fire.
Run migrations as a release step before starting the new version. Concurrent migrations wait on a lock.
Shut down without interrupting runs
On SIGTERM or SIGINT, Adapt stops claiming new runs.
SHUTDOWN_DRAIN_SECONDS=0 # time active runs get to finish; default 0
SHUTDOWN_SERVE_SECONDS=0 # minimum time to keep answering requests; default 0
- With the default of 0, active runs are interrupted at once. Interrupted runs are marked interrupted, not resumed.
- Set
SHUTDOWN_DRAIN_SECONDSto at least your agents' longest time limit (five minutes by default). Once the serve window is over, a run still going stops after its current step and goes back in the queue for another process to continue. - Set
SHUTDOWN_SERVE_SECONDSto the time your load balancer needs to stop sending requests. - Your process manager must wait longer than the larger of the two, plus 60 seconds. Docker's default stop timeout is 10 seconds and Kubernetes' default grace period is 30 seconds, so raise them. A second signal ends both waits at once.
With one replica, queued runs and incoming surface messages wait for the next process to start.
Next steps
- Sign in and follow Get started.
- Read Security and privacy for what Adapt stores and who can see it.