Self-Hosting
Most customers use Achilles as a managed service. If your policies require it, you can run the platform in your own cloud account or data center, so conversations, credentials, and audit records stay inside your boundary. This page gives your infrastructure team the shape of the deployment. Your Achilles contact provides the container images and detailed setup guide.
Components
| Component | Role | Notes |
|---|---|---|
| Agent API | Runs agents, enforces permissions, serves every client | The only component the others depend on. Needs WebSocket support for voice and streaming. |
| Console | Web app where your team builds, tests, and monitors agents | Static site pointing at the API |
| Widget | The chat script you place on your websites | One static file |
| PostgreSQL | Agent definitions and versions, sessions, audit records, encrypted credentials | Required for production |
| Redis | Short-lived conversation history, pending approvals, message queues | Required for production message channels |
| AI model provider | Reasoning and language | Hosted provider or a model you run yourself |
Requirements
- A container platform or virtual machine able to run a long-lived Node.js 20 or later service.
- A managed or self-run PostgreSQL database with a pooled connection string.
- Redis with TLS for production.
- Outbound HTTPS to your model provider, unless the model is self-hosted, and network access to the systems the agent reads.
- Static hosting for the console and widget, or any web server.
- A secrets manager for the keys listed below.
For a trial with no database or model account, the platform can run in a demo mode with canned answers and read-only sample agents. Do not use this for real users.
Configuration overview
Configuration is by environment variables on the API. Generate each secret once with a strong random generator and store it in your secrets manager.
| Setting | Purpose |
|---|---|
| End-user signing secret | Signs and verifies user tokens. The API will not start without it. |
| Console signing secret | Signs console logins. Must differ from the one above. |
| Admin API key | Lets automation reach admin endpoints. In production, admin calls are refused when it is unset. |
| Database URL | Where the platform stores its own data |
| Redis URL | Conversation state and queues |
| Credential encryption key | Encrypts datasource credentials you enter in the console |
| Model provider keys and model list | Which AI providers are enabled |
| Allowed origins | Websites and console addresses allowed to call the API |
| Console API address | Set when building the console. Rebuild if the API moves. |
Your own business databases are not configured here. Your workspace admin enters those in the console under Datasources, where they are encrypted. See Integration overview.
Deploy targets
| Piece | Typical target |
|---|---|
| Agent API | A container service on your cloud, or a Kubernetes deployment. Port 3100, health path /health. |
| PostgreSQL | Your managed database service |
| Redis | Your managed cache service, over TLS |
| Console and widget | Static hosting or a CDN |
| Background workers | Run inside the API by default. For heavy messaging traffic, run the same image as a separate worker against the same Redis and database. |
Deployment order that works well: create the database and load the schema, set secrets and the model provider, start the API and check health, enter datasource credentials, then publish the console and widget and add their addresses to the allowed origins.
Health checks
The API exposes a no-login health endpoint. Use it as your container health check and as a deploy gate.
curl https://api.example.com/health
A healthy response reports an ok status, and for each agent a health score and whether it is ready to deploy. After deploying:
- Health reports every agent as ready.
- Sign up in the console as the first operator, which also creates your first workspace.
- Send a message in the Playground.
- Confirm the session appears in Monitor.
- Edit an agent and publish to confirm reload works.
Operating tips
- Free-tier hosts sleep when idle. Ping the health endpoint every 10 to 14 minutes, or use an always-on plan.
- Audit records grow steadily. Plan retention and pruning with your compliance team.
- Rotate the admin key and signing secrets on your normal schedule. Rotating the console secret signs everyone out.
- Without Redis, conversations do not survive a restart and queued messages are not retried.
- Schema updates are applied by re-running the provided setup script, which is safe to repeat.