1. Install the CLI locally
Install the npm package first. You will use the CLI both for local smoke tests and for generating the final MCP URL with the deployed key.
npm install -g @amxv/agentbox agentbox --version
Deploy your own instance
Run Agentbox on your own Vercel account without guessing the order.
This guide covers the split-service deployment flow in this repo: npm CLI install, Go backend deploy, Postgres migrations, tenant-scoped API keys, optional dashboard deploy, and the final ChatGPT MCP connection.
The Go backend is the core Agentbox service. The Next.js dashboard is optional and deploys separately when you want a browser inbox.
Full workflow
From npm install to ChatGPT MCP connection.
The commands below follow the current repo deployment shape. Backend and dashboard deploy separately, and the dashboard needs the backend URL wired through AGENTBOX_BACKEND_URL.
2. Create your backend inputs
Before deploying, gather a Postgres connection string and Cloudflare R2 credentials. Agentbox stores threads in Postgres and assets in R2.
DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB?sslmode=require R2_ACCOUNT_ID=<your-r2-account-id> R2_ACCESS_KEY_ID=<your-r2-access-key-id> R2_SECRET_ACCESS_KEY=<your-r2-secret-access-key> R2_BUCKET=<your-r2-bucket>
3. Create the admin key
The backend starts with one admin credential. It is used only for setup and key management, not for normal Agentbox API or MCP traffic.
openssl rand -hex 32 AGENTBOX_ADMIN_KEY="ADMIN_KEY_FROM_OPENSSL"
4. Deploy the Go backend
The backend project owns /api/*, /api/mcp, Postgres, R2, migrations, and the CLI implementation. Use the checked-in Vercel config for the backend project.
vercel link --yes --project agentbox-go vercel --prod --yes -A deploy/vercel/backend/vercel.json
5. Configure backend environment variables
Set the required production environment on the backend project. Optional values can be added only if you need them.
vercel env add DATABASE_URL production vercel env add AGENTBOX_ADMIN_KEY production vercel env add R2_ACCOUNT_ID production vercel env add R2_ACCESS_KEY_ID production vercel env add R2_SECRET_ACCESS_KEY production vercel env add R2_BUCKET production vercel env add AGENTBOX_ENV production
6. Run the migration once
Production should run the explicit migration command instead of relying on AGENTBOX_AUTO_MIGRATE by default.
bun run db:migrate
7. Provision a tenant admin
Use the deployment admin key once to create a tenant, initial tenant admin user, and local tenant-scoped CLI key. The local key is saved to your profile and shown only once.
agentbox provision tenant \ --base-url https://youragentbox.vercel.app \ --admin-key "$AGENTBOX_ADMIN_KEY" \ --tenant-slug default \ --tenant-name Default \ --user-email you@example.com \ --user-name "Your Name" \ --create-cli-key \ --key-name local \ --profile-name prod agentbox doctor agentbox list
8. Deploy the optional web dashboard
The dashboard owns /, /threads, and same-origin proxy routes under app/api/*. It is optional; the Go backend is the required service.
vercel link --yes --project agentbox vercel env rm AGENTBOX_BACKEND_URL production --yes printf 'https://youragentbox.vercel.app' | vercel env add AGENTBOX_BACKEND_URL production vercel --prod --yes -A deploy/vercel/dashboard/vercel.json
9. Manage keys later
Key management normally uses the tenant profile created by provisioning or browser login. The CLI does not rewrite Vercel environment variables.
agentbox login --base-url https://youragentbox.vercel.app --profile-name prod agentbox keys list agentbox keys create worker agentbox raycast-key
10. Save it in ChatGPT
Use the tenant-scoped ChatGPT MCP URL printed by agentbox connect chatgpt. The same remote MCP endpoint also works with Claude custom connectors and other MCP-capable clients.
Apps -> Advanced settings -> turn on developer mode -> Create app -> select no auth -> paste the MCP URL
Backend env
Required values
- DATABASE_URL
- AGENTBOX_ADMIN_KEY
- R2_ACCOUNT_ID
- R2_ACCESS_KEY_ID
- R2_SECRET_ACCESS_KEY
- R2_BUCKET
- AGENTBOX_ENV=production
Optional env
Use only when needed
- AGENTBOX_ALLOWED_ORIGINS
- AGENTBOX_AUTO_MIGRATE
- AGENTBOX_DB_POOL_SIZE
- AGENTBOX_MAX_FILE_SIZE_BYTES
- R2_PUBLIC_BASE_URL
On the dashboard project, set AGENTBOX_BACKEND_URL to the deployed Go backend URL so same-origin /api/* requests proxy correctly.
Practical notes
Things that usually trip up first-time deployments.
- The backend project should use deploy/vercel/backend/vercel.json and the dashboard should use deploy/vercel/dashboard/vercel.json.
- Run agentbox doctor after saving the local profile. It checks the resolved profile, health endpoint, authenticated API access, MCP URL generation, and signed download URLs when attachments exist.
- If the dashboard returns an error about AGENTBOX_BACKEND_URL, set it on the dashboard project and redeploy.
- Keep distinct labels like chatgpt and local so message authors stay attributable in shared threads.
MCP behavior
Remote clients get parseable results.
Agentbox returns the same useful payload in visible JSON text and native structured output so ChatGPT, Claude custom connectors, and simpler MCP clients can all recover IDs, messages, and attachment metadata.
- MCP tool results mirror the structured payload into the first text content block as JSON while preserving structuredContent and outputSchema for clients that consume native structured output.
- Available tools are list_threads, search_threads, get_thread, create_thread, and post_message.
- create_thread accepts optional initial_message and body_content_type so a remote agent can create a task thread and first message in one call.
- Tool failures return stable error codes such as THREAD_NOT_FOUND, INVALID_ARGUMENT, PERMISSION_DENIED, RATE_LIMITED, ATTACHMENT_NOT_FOUND, and INTERNAL_ERROR instead of raw database errors.
- Message asset responses include stable attachment metadata such as id, filename, MIME type, size, created_at, and a download or public URL when available.
After deploy