Skip to content

Architecture

How AgntSpark runs today. The platform currently runs on a single host; this page describes that deployment, not a future one.

                          ┌──────────────────────────────────────────────┐
  console / API           │  Host                                        │
  agntapi.agntspark.com ─────▶ Caddy (TLS) ──▶ Gateway ──▶ Postgres       │
                          │     │    ▲           │    └──▶ Redis          │
  agent URLs              │     │    │ route?    │ Docker API             │
  *.run.agntspark.com ───────▶  │    └───────────┤                        │
                          │     ▼                ▼                        │
                          │  ┌────────┐ ┌────────┐ ┌────────┐             │
                          │  │agent A │ │agent A │ │agent B │  …          │
                          │  │replica │ │replica │ │replica │             │
                          │  └───┬────┘ └───┬────┘ └───┬────┘             │
                          └──────┼──────────┼──────────┼──────────────────┘
                                 ▼          ▼          ▼
                          model providers (OpenAI, Anthropic, Google) and your APIs

Components

Caddy terminates HTTPS for the console, the API and every agent URL. Agent certificates are issued the first time a hostname is visited, and only for hostnames that belong to an agent.

Gateway (agntspark-gateway, FastAPI) is the API and the control plane. It authenticates users and API keys, enforces roles and plan quotas, stores agent configuration in Postgres, and starts, scales and stops agent containers through Docker. A scheduler checks every running agent every 30 seconds: it syncs status and replica counts, meters usage, and applies auto-scaling.

Agent containers run your image or the platform runtime (agntspark-core), which serves the runtime contract.

Postgres holds accounts, agents, keys, invites and hourly usage. It's backed up nightly. Redis backs login rate limiting.

A request to an agent

  1. A client calls https://support-k3v9qa.run.agntspark.com/invoke.
  2. Caddy asks the gateway where to send it. The gateway looks up the agent by hostname, then:
    1. applies the per-caller rate limit,
    2. checks the access key if the agent is private,
    3. applies the plan's per-agent rate limit,
    4. picks a random running replica and counts the request.
  3. If any check fails, Caddy returns the gateway's answer (401, 404, 429 or 503) to the client.
  4. Otherwise Caddy proxies the request directly to the replica. The request body and the response never pass through the gateway.

Isolation

Agents from different accounts share the host's kernel. Between them:

  • Each agent runs in its own containers with CPU, memory and process limits, no extra Linux capabilities, and no privilege escalation.
  • Agent containers are on a separate network from the gateway, database and Redis, and firewall rules block traffic between agent containers. Agents reach each other only through their public URLs.
  • The cloud metadata service is blocked.
  • Secret environment variables and model keys are encrypted at rest and only decrypted when a container starts.

Container isolation isn't as strong as a virtual machine per tenant, which is one reason registration is invite-only during the alpha. Stronger sandboxing is on the roadmap.

Current limits of this design

  • One host: no redundancy yet, and capacity is that machine's.
  • Images must be public and pre-built; there's no build service.
  • Conversation state lives in each replica's memory.
  • Logs are the containers' recent output, not a searchable store.