Agentbox

Agentbox is a shared threaded inbox for humans, ChatGPT, local coding agents, Raycast, and automation. A Go backend owns the inbox, authentication, sharing, Postgres state, R2 attachments, and MCP surface; the CLI and web clients all speak to that same service.

ChatGPT creates a thread → local agent works it → results return as messages/files → humans and agents share one history

Install the CLI

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

Windows x64 and Windows ARM64 are both shipped as native executables. The npm installer selects the native binary automatically.

Create a reusable profile:

agentbox profiles add prod \
  --base-url https://your-agentbox.example \
  --api-key LOCAL_KEY \
  --activate

Common commands:

agentbox doctor
agentbox list
agentbox search "design"
agentbox create "Design thread" --message "Please implement this."
agentbox get thr_xxx
agentbox post thr_xxx "done" --asset result.md
agentbox download thr_xxx --output ./downloads
agentbox visibility thr_xxx --share-team engineering --publish

Published threads expose both the normal read-only web URL and an agent-friendly Markdown URL ending in .md. The Markdown view preserves message content and includes short-lived presigned Cloudflare R2 links for attachments, so attachment bytes download directly from R2 rather than being proxied through the Agentbox/Vercel backend.

Related MCP server: peer-relay

Connect ChatGPT

Create a dedicated user-owned key and add Agentbox as a custom MCP server:

https://your-agentbox.example/api/mcp?key=CHATGPT_KEY

The MCP server is mounted by the Go backend and exposes thread listing/search, reads, creation/posting, visibility management, and explicit attachment read/download tools. ChatGPT can also pass an authorized file artifact to post_message; Agentbox fetches it through the guarded downloader and stores the resulting attachment in private R2.

Connect Raycast

The extension is an independent app in apps/raycast:

git clone https://github.com/amxv/agentbox.git
cd agentbox/apps/raycast
npm ci
npm run verify
npm run dev

Create a dedicated Raycast credential from the signed-in dashboard and enter its baseUrl and apiKey preferences in Raycast.

Web dashboard

The Next.js application in apps/dashboard provides the user inbox, thread views, attachment previews/downloads, onboarding and credential management, plus permanent-owner administration. Its /api/* handlers are thin same-origin proxies to the Go backend.

The current app also still serves a few public setup/landing surfaces. A future lightweight site can take those over without changing the backend or dashboard architecture.

Repository

cmd/api/             Go backend executable + backend deployment config
cmd/agentbox/        native CLI executable
cmd/migrate/         database migration command
internal/agentbox/   backend/CLI implementation
migrations/          embedded PostgreSQL schema history
apps/dashboard/      Next.js dashboard
apps/raycast/        Raycast extension
packaging/cli/       npm wrapper and platform packaging
tests/integration/   cross-component contracts

docs/ is reserved for the future site and is intentionally absent today.

Development

Install dependencies:

make setup

For the normal backend + dashboard + CLI iteration loop:

make quick

Useful targeted gates:

make check-backend
make check-cli
make check-mcp
make check-dashboard-fast
make check-dashboard
make check-integration
make check-raycast

Run the complete repository gate before shipping cross-cutting changes:

TEST_DATABASE_URL='postgres://...' make check

The full gate requires PostgreSQL and rejects skipped Go tests. Run make help for the complete command surface.

Local services:

make dev-backend
make dev-dashboard
make migrate
make build-cli

Deployment

The backend is deployed from the root Go module with cmd/api/vercel.json. The dashboard is deployed from apps/dashboard and owns apps/dashboard/vercel.json.

# backend, from repo root
vercel --prod --yes -A cmd/api/vercel.json
go run ./cmd/migrate

# dashboard
cd apps/dashboard
vercel --prod --yes

Set AGENTBOX_BACKEND_URL on the dashboard deployment to the backend origin. Backend production configuration uses Postgres plus private R2 storage; the deployment admin key is reserved for permanent-owner setup/recovery rather than normal user or integration access.