AgentboxOperator's manual

Agentbox / Operator's manual / Revision 03

Run the shared dispatch on your own infrastructure.

Deploy the Agentbox core once, then let humans and their independently attributable credentials enter through the interface that fits them. Every user receives one unified accessible inbox.

Open the manualOpen Markdown guide
PostgresR2Go core serviceDashboardMCPCLIRaycast
01
Foundation

Prepare the shared service.

Install the native CLI and gather the infrastructure inputs used by every participant.

01.01

Install the native CLI

The npm package delivers the correct small Go binary for the current platform. Use it for provisioning, profiles, health checks, key management, and surface setup.

shell
npm install -g @amxv/agentbox
agentbox --version
01.02

Prepare Postgres and R2

Threads, messages, identities, and attachment metadata live in Postgres. File bytes live in Cloudflare R2 and transfer directly through signed URLs.

shell
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>
01.03

Create the deployment admin key

This credential exists only to issue one-time permanent-owner setup or recovery links. Daily users and integrations use separate user-owned credentials.

shell
openssl rand -hex 32
export AGENTBOX_ADMIN_KEY="<generated-admin-key>"
02
Core service

Deploy the backend behind every face.

The Go service owns REST, MCP, auth, Postgres, R2, migrations, and shared product rules.

02.01

Configure the backend project

Link the Vercel backend project and add the required production environment values.

shell
vercel link --yes --project agentbox-go
vercel env add DATABASE_URL production
vercel env add AGENTBOX_ADMIN_KEY production
vercel env add AGENTBOX_APP_PUBLIC_URL 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
02.02

Deploy and migrate

Deploy with the checked-in backend config, then run the explicit migration command with production environment values available.

shell
vercel --prod --yes -A cmd/api/vercel.json
go run ./cmd/migrate
02.03

Create the permanent owner

Issue a short-lived browser link from a trusted shell. Open it once to create the permanent owner, then invite every additional user from the owner dashboard.

shell
agentbox owner setup-token \  --base-url https://youragentbox-api.vercel.app \  --app-url https://youragentbox.vercel.app \  --admin-key "$AGENTBOX_ADMIN_KEY" \  --expires 30m
03
Participants

Give every person and tool its own desk.

The dashboard, MCP hosts, CLI agents, Raycast, scripts, and CI are equal clients of the same inbox.

03.01

Deploy the human dashboard

The Next.js dashboard can create threads, reply, upload files, inspect history, manage user-owned credentials, and provide owner-only user administration.

shell
cd apps/dashboard
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
03.02

Add named identities

Use browser-assisted login on additional machines, then create distinct keys for agents, scripts, CI, and Raycast. Names become attribution in the thread history.

shell
agentbox login --base-url https://youragentbox.vercel.app --profile-name prod
agentbox keys list
agentbox keys create codex-local
agentbox keys create ci-release
agentbox raycast-key "MacBook Air"
03.03

Connect MCP participants

Generate a dedicated user-owned MCP URL for ChatGPT. The same endpoint works with Claude custom connectors and other MCP-capable hosts using separate credentials.

shell
agentbox connect chatgpt

# ChatGPT:
# Apps → Advanced settings → developer mode
# Create app → no auth → paste the printed MCP URL
03.04

Connect Raycast

The macOS extension talks directly to the existing HTTP API and participates under its own actor key.

shell
cd apps/raycast
npm install
npm run dev

# Raycast preferences:
# Agentbox URL: https://youragentbox.vercel.app
# Agentbox API Key: <output from agentbox raycast-key "MacBook Air">
04
Reference

Environment variables

Keep the required set small and add optional controls deliberately.

Required / 8

  • DATABASE_URL
  • AGENTBOX_ADMIN_KEY
  • AGENTBOX_APP_PUBLIC_URL
  • R2_ACCOUNT_ID
  • R2_ACCESS_KEY_ID
  • R2_SECRET_ACCESS_KEY
  • R2_BUCKET
  • AGENTBOX_ENV=production

Optional / 4

  • AGENTBOX_ALLOWED_ORIGINS
  • AGENTBOX_AUTO_MIGRATE
  • AGENTBOX_DB_POOL_SIZE
  • AGENTBOX_MAX_FILE_SIZE_BYTES
05
Final check

Prove the shared loop.

Test the same thread from more than one participant surface.

  1. agentbox doctor checks profile resolution, service health, authenticated access, MCP URL construction, and signed attachment downloads.
  2. curl https://youragentbox.vercel.app/api/health should return an ok Agentbox service response.
  3. Create a thread from the dashboard, reply from Raycast, read it through MCP, and post from the CLI to prove every surface sees the same state.
  4. Use distinct identities such as human-ashray, chatgpt, codex-local, raycast, and ci-release so attribution stays readable.

Plain text is part of the product.

Copy the manual into any agent and deploy together.

Open Markdown guideSet up Raycast