Self-Host (Business tier)

Self-Host

Business-tier subscribers can run ACECode on their own infrastructure. Your code, your embeddings, and your LLM keys stay inside your perimeter — ACE talks to your chosen LLM providers directly, never to our cloud.

Caution

Self-host is Business tier only ($199/mo+). Free / Pro / Max users must use the hosted instance at api.acecode.dev. Self-host enforcement is via license-key gating in the Hono server.

What you provision

A single Linux VPS or container can run the entire stack. Minimum specs:

Component	Spec	Notes
CPU	4 vCPU	Indexing parallelism scales linearly
RAM	8 GB	Postgres + Redis + Node.js
Disk	50 GB SSD	Chunks + embeddings + KB; scales with indexed lines
OS	Ubuntu 22.04 / 24.04, Debian 12, or Docker-capable host

Production recommended: 6 vCPU / 12 GB RAM / 100 GB SSD. This matches our hosted instance and handles ~5M indexed chunks comfortably.

Stack overview

┌─────────────────────────────────────────┐
│           Caddy (reverse proxy)          │
│  TLS termination, HTTP/2, automatic LE   │
└────────────────────┬────────────────────┘
                     ↓
┌─────────────────────────────────────────┐
│        @ace/api (Hono on Node 22+)       │
│   MCP server + REST API + indexer       │
└─────┬─────────────────────────┬─────────┘
      ↓                         ↓
┌─────────────┐         ┌──────────────┐
│ PostgreSQL  │         │   Redis 7    │
│ + pgvector  │         │              │
│ (all data)  │         │  (cache)     │
└─────────────┘         └──────────────┘
      ↑
┌─────────────────────────────────────────┐
│   External LLM + Embedding providers     │
│   Voyage (embed) + your choice of LLM   │
└─────────────────────────────────────────┘

Quick start (Docker Compose)

1. Get the Docker Compose bundle

   Business tier customers receive a private Compose bundle. The bundle ships:

   • docker-compose.yml — services: api, postgres, redis, caddy
   • Caddyfile — TLS-terminated reverse proxy
   • .env.example — required env vars
   • init.sql — pgvector extension + initial migrations

2. Provide LLM keys

   ACE doesn’t ship LLM credentials. Add your own to .env:

   # Required: embedding provider
   VOYAGE_API_KEY=pa-...
   
   # At least one LLM provider (more = better fallback)
   XAI_API_KEY=xai-...
   GOOGLE_API_KEY=...
   OPENAI_API_KEY=sk-...           # or any OpenAI-compatible endpoint
   NINEROUTER_BASE_URL=http://...  # if using 9router gateway

3. Set your domain + license key

   ACE_DOMAIN=ace.your-company.com
   ACE_LICENSE_KEY=<provided-with-subscription>

4. Start the stack

   docker compose up -d
   docker compose exec api pnpm db:push       # apply schema
   docker compose exec api pnpm seed:admin    # create first admin user

5. Verify

   curl https://ace.your-company.com/v1/health
   # → { "status": "ok", "version": "x.y.z" }

6. Connect the CLI

   export ACE_API_URL=https://ace.your-company.com
   export ACE_API_KEY=<from-admin-dashboard>
   ace init
   ace index

Self-host vs hosted differences

Feature	Hosted (api.acecode.dev)	Self-host (Business)
Latency from your region	Depends — US-east origin	Wherever you put it
Code privacy	Hosted on our infra	Stays inside your perimeter
LLM provider keys	We provide + pool	You provide + manage
Indexed-chunk limit	Tier-capped	Bounded by your disk
Upgrades	Automatic	git pull && docker compose up -d
Backup	Automatic snapshots, off by default	Your responsibility
SSO	Not yet	SAML 2.0 / OIDC (Business only)
Audit log	Not surfaced	Postgres admin_activity_log table
Support SLA	Best-effort	24h response (Business)

Migrating from hosted to self-host

If you started on hosted and want to move on-premises:

1. Export — ace export --project=<slug> produces a tarball with files + chunks + embeddings + memories. Embeddings are portable (same Voyage model on both sides).
2. Restore — on your self-hosted instance: ace import <tarball> re-creates the project with all data.
3. Switch endpoint — point your CLI / VS Code extension at the new host: ACE_API_URL=https://ace.your-company.com.

Embeddings re-importing avoids re-billing Voyage tokens. Expect ~5 minutes per 100K chunks for the import step.

Hardening checklist

• Postgres on a private network, not bound to public IP
• Redis bound to 127.0.0.1 only (it does not need network access)
• Caddy auto-HTTPS, force HTTPS redirect
• LLM provider keys in a secrets manager, not in .env on disk
• Daily pg_dump to off-host storage
• OS auto-updates enabled (unattended-upgrades on Debian/Ubuntu)
• Firewall: only ports 80 + 443 open inbound

Support

Business-tier self-host comes with:

• Private support channel (Slack Connect or Discord)
• 24h response SLA on infra issues
• Direct line to the founding team for architectural questions
• Pre-release access to new MCP tools

Email support@acecode.dev for self-host onboarding.