Operations

Run Agent Studio in production

Validate production configuration, build Agent Studio, start the Next.js server, and verify process liveness.

Build and start Agent Studio with production configuration that passes its server-side validation. This guide covers the product-supported build and start scripts; your organization remains responsible for process supervision, TLS termination, deployment rollback, backups, and dependency monitoring.

Before you begin

Complete Install Agent Studio and provision the database and authentication settings required by your deployment. Run these steps from the Agent Studio project directory with dependencies already installed.

You need authority to set runtime environment variables and start the service. Keep secrets in your platform's secret store, not in shell history or a committed file.

Deployment flow

The build must complete before the server starts. A successful liveness check confirms the web process, while dependency checks remain a separate operational responsibility.

Build and start

Set required configuration

Set NODE_ENV to production, provide a database URL and a nonempty authentication secret, and set the public application URL to the externally reachable HTTPS origin.

bash

export NODE_ENV=production
export DATABASE_URL='postgresql://app_user:REDACTED@db.example.com:5432/agent_studio'
export NEXTAUTH_SECRET='REPLACE_WITH_A_SECRET_FROM_YOUR_SECRET_STORE'
export NEXT_PUBLIC_APP_URL='https://studio.example.com'

DATABASE_URL must be a URL or begin with postgresql://. NEXT_PUBLIC_APP_URL must be a valid URL. Do not copy the example credentials into a deployment.

Add enabled integration settings

Set the keys for the services your deployment uses. Clerk settings are NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY; model-provider settings include OPENAI_API_KEY, GROQ_API_KEY, and OPENROUTER_API_KEY.

Other optional settings include MCP_ACCESS_TOKEN, COMPOSIO_API_KEY, ARCADE_API_KEY, A2A_REGISTRY_URL, and A2A_REGISTRY_TOKEN. A2A_REGISTRY_URL, when set, must be a valid URL. Leave unused optional integrations unset rather than inserting placeholder secrets.

Choose the log level

Set LOG_LEVEL to one of fatal, error, warn, info, debug, or trace. If you omit it, Agent Studio uses info.

bash

export LOG_LEVEL=info

The selected value is available when the server configuration loads. An unsupported value fails production validation.

Build the application

Run the package script that invokes next build:

bash

npm run build

Continue only when the command exits successfully. In production server mode, invalid or missing required environment values produce a fatal configuration error and terminate the process; correct the named fields before rebuilding.

Start the production server

Start the built application with the package script that invokes next start:

bash

npm run start

Keep the same validated environment available to the started process. The command should remain running and accept requests on the address configured for the Next.js server by your hosting environment.

Verify the running process

From a network location that reaches the deployment, request the public health route:

bash

curl --fail-with-body --silent \
  https://studio.example.com/api/health

The response must report "status":"ok" and "service":"agent-studio" with a current timestamp. Then exercise the database, Clerk session, and any provider or integration required by your production workload.

✅The deployment has passed the product-level check when the production build succeeds, npm run start remains running, and /api/health returns the expected service payload. Dependency-specific checks are still required before accepting workload traffic.

Operational constraints

Configuration is parsed by the server. Production validation is strict: invalid configuration logs a fatal error and exits instead of using development fallback values.
NEXT_PUBLIC_APP_URL defaults to http://localhost:3000; set it explicitly to the external production origin so the deployment does not retain the local default.
The health route is liveness-only. It does not establish database, provider, MCP, or scheduler readiness.
The source does not define a backup, restore, rolling-upgrade, or rollback procedure. Establish and test those controls for your hosting and database platform before a change.
Start only the built output in production. The dev script runs the development server and is not the production start path.

Troubleshooting

If the build or server exits with Invalid environment variables in production, use the formatted field errors to correct the configuration. Check URL syntax for DATABASE_URL, NEXT_PUBLIC_APP_URL, and A2A_REGISTRY_URL; confirm NODE_ENV=production; and choose a supported LOG_LEVEL.

If /api/health responds but a signed-in or integration workflow fails, leave the liveness probe unchanged and diagnose the failing dependency. See Monitor service health for signal boundaries and Troubleshoot Agent Studio for API error handling.

Next steps

Review Environment variable reference for configuration scope, then apply Authentication and authorization model when exposing the deployment to users and API clients.