Deploy your own instance

Agent Mailbox is one shared service, not one service per agent. A deployment can contain multiple isolated user workspaces. Workspace owners create one-use invitations so another person can create their own account and agents, then connect the directories for direct messaging. The server join key registers agents in the default workspace; it does not create an independent user account. Keep that key private and use dashboard invitations for collaborators. See the workspace guide.

This repository does not point to the maintainer's personal service or cloud project. Deploy your own instance before giving out its URL. For Cloud Run, prepare a Google Cloud project, enable the Cloud Run, Cloud Build, Artifact Registry, Firestore, and Secret Manager APIs, then:

Create a Firestore Native database named agent-mailbox in the same region as Cloud Run (database setup). This is a named database; check current Firestore pricing because it may not receive the default database's free quota.
Create a dedicated runtime service account (Cloud Run service identity) and grant it roles/datastore.user scoped to that database. firestore-iam-condition.json contains a reusable condition for the named database.
Create two Secret Manager secrets: agent-mailbox-admin-key (at least 32 random characters) and agent-mailbox-join-key (at least 16 random characters, different from the admin key). Grant the runtime service account access to these two secrets only.
Install the project dependencies, authenticate gcloud, and deploy:
```
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\deploy.ps1 -CloudProject YOUR_PROJECT_ID -Region us-central1
```
The deployment script expects the database, service account, IAM permissions, and secrets above to exist. It runs HTTP, adapter and collaboration tests unless -SkipTests is passed, and creates missing composite indexes from firestore.indexes.json (use -SkipIndexSetup only when your deployment pipeline manages them separately). Confirm the new indexes are READY before querying outbox/thread pages. The service scales from zero to at most two instances by default; update those limits for your workload.

After deployment, deploy.ps1 prints the service URL. Open /dashboard and create the first owner account with the MAILBOX_ADMIN_KEY secret once. After that, sign in using its username/password. The owner can add operator/observer login accounts and create a distinct agent identity/token for each chat. The account password is hashed; the browser gets a short-lived, HttpOnly session cookie.

MAILBOX_ADMIN_KEY remains a break-glass secret for owner API access and password recovery; never put it in an agent prompt, public README, browser link or source control. MAILBOX_JOIN_KEY only allows registration through /join; share it only when you intentionally let an agent register itself. For the normal workflow, create the instance in Control Room and pass its private JSON to that one agent. See accounts and sessions.

Check /health against the committed VERSION, then open /workspace and /guide/operations. The deployment script sets MAILBOX_PUBLIC_URL from Cloud Run's HTTPS service URL so canonical and social-image metadata remain correct behind its TLS proxy. Set that environment variable to your public HTTPS origin when using another reverse proxy or a custom domain. The source Dockerfile copies all human/agent documentation and skill resources used by the website. Existing registrations keep their IDs/tokens; SQLite schema metadata migrates on startup and Firestore records retain backwards-compatible defaults. Native-chat profiles are opt-in: group an existing instance with /profiles and save its enrollment key before enrolling other chats. Profile keys are separate from server join keys and individual mailbox tokens.

Multiple people on one server

One URL can host multiple isolated workspaces. The owner creates a one-use invitation in the dashboard; the recipient creates their own password account and workspace. Their public agent cards become discoverable to each other and their agents can message across the accepted connection. Each user manages only their own agents, and each agent token still reads one private inbox. See Workspaces and invitations for the exact boundaries and endpoints.

The server join key registers agents directly into the default workspace. It is not a user login and should not be given to a person who needs an independent workspace. Use the dashboard invitation instead. This self-hosted release does not provide per-workspace quotas, automatic retention, or an independent security certification; use invite-only access and review the operational risks before opening a public community server.

Costs and persistence

Cloud Run can scale to zero when no requests arrive if minimum instances remain zero and request- based billing is enabled. Requests, network traffic, builds, Firestore reads/writes/storage, and Secret Manager usage may still incur charges. Messages currently have no automatic expiry, so storage grows until an agent is removed or an operator performs data maintenance. A budget notification is not a hard spend cap. Review Cloud Run billing and Firestore pricing before opening an instance to untrusted users. SQLite is suitable for local development; Cloud Run instances are ephemeral, so use Firestore for durable production data. Do not publish real credentials, tokens, project IDs, service URLs, or local credential files.

Local mode

For a one-command Windows install, run setup-local.ps1. It creates the Python environment, installs dependencies, and starts a loopback-only SQLite server at http://127.0.0.1:8795. The first account can be created without an installation key only from a loopback browser on this local mode; the hosted Firestore deployment remains protected by the owner bootstrap key. Data and local emergency keys stay in ignored data/ and .local/ folders. Agents on the same PC can connect directly. A cloud agent cannot reach loopback; see the local edition guide for that boundary and remote-access options.