What is q15?

q15 (Quietscheentchen) is a self-hosted, Telegram-based AI agent runtime built in Go. You talk to it through Telegram; it runs code, reads and writes files, searches the web, manages a persistent knowledge base, and maintains layered memory across conversations.

It is not a cloud service. You run it in Docker Compose or Kubernetes. Your workspace, memory, and skills persist on your own infrastructure.

How a turn works

sequenceDiagram
    participant User
    participant Agent as q15-agent
    participant Exec as q15-exec
    participant Proxy as q15-proxy
    participant Model as LLM
    participant Internet

    User->>Agent: Telegram message
    Agent->>Agent: Assemble prompt<br/>(core memory, working memory, history)
    Agent->>Agent: Select model<br/>(capability inference, fallback order)
    Agent->>Model: Send prompt + tools
    Model-->>Agent: Response (text or tool calls)
    loop Tool execution
        Agent->>Exec: Shell command (gRPC)
        Exec->>Proxy: Egress request
        Proxy->>Internet: Forward (with credentials if rule matches)
        Internet-->>Proxy: Response
        Proxy-->>Exec: Response (credentials stripped)
        Exec-->>Agent: Command output
    end
    Agent->>Agent: Persist turn to /memory/history/
    Agent->>User: Telegram response

The three services

q15 is not a monolith. It is three services, each with a clear ownership boundary.

Service	Owns	Listens
q15-agent	Prompt assembly, tool wiring, Telegram I/O, memory, file operations	Telegram (long-poll)
q15-exec	Command execution, session lifecycle, Nix package management	:50051 (gRPC)
q15-proxy	Credential injection, request mutation, TLS interception	:50052 (proxy), :18080 (PAC)

q15-agent connects to q15-exec at q15-exec:50051. q15-exec routes all outbound traffic through q15-proxy at q15-proxy:50052. The agent never talks to the proxy directly — the exec service is the egress boundary.

A fourth service, q15-qdrant, stores embedding vectors when the embeddings tool is configured.

Why this separation matters

Most AI agent platforms run everything in one process: the model, the tools, the credentials, and the network access all share a trust domain. If the model is compromised via prompt injection, the attacker has everything.

q15 splits the harness into three services with hard boundaries:

• Credentials live in the proxy, not the agent. The agent never sees API tokens or passwords. When it makes a request to api.github.com, the proxy attaches the token at the network layer. A compromised prompt cannot exfiltrate secrets the agent never had.
• Execution is isolated. Commands run through q15-exec via Nix, not through a general-purpose host shell. File access is rooted to /workspace, /memory, and /skills.
• Egress is unconditional. The agent cannot ask exec to bypass the proxy — the routing is configured at the deployment level.

This is harness engineering: the architecture makes a compromised model safe by constraining what it can actually do.

Storage contract

Every stack has persistent volumes:

Path	Purpose
/workspace	Durable project tree and working files
/memory	Agent identity, semantic knowledge, working state, history
/skills	Installed skill artifacts
/nix	Nix store and fetched packages (keeps builds warm across sessions)
/var/lib/q15/proxy	Proxy-owned durable state

/workspace may start empty on first deploy. That is a valid initial state. It is expected to persist long-term and survive restarts and upgrades.

Deployment model

One stack = one q15-agent + one q15-exec + one q15-proxy, running together in Compose or Kubernetes. Optionally a q15-qdrant sidecar for embeddings.

In Kubernetes, the supported topology is one namespace per q15 stack. Each stack contains its own ConfigMaps, Secrets, and persistent volumes. The namespace is the isolation boundary.

Auth bootstrap

Interactive auth is handled separately by q15-auth, an operator tool that runs on your machine, not inside the runtime containers. It produces auth.json, which gets mounted into the agent container.

Where to next

Get started

Clone, configure, and run a local stack in under 10 minutes.

Prompt Injection

Why prompt injection is the fundamental challenge of AI agents, and how q15 defends against it.

Services

Deep dive into q15-agent, q15-exec, and q15-proxy.