The AI Assistant is an optional helper that investigates your instance and deployments, explains what it finds, and proposes corrective actions. It runs as a conversation: you ask a question, the assistant gathers facts with read-only tools, and it answers. Any action that would change something waits for your approval.
Bring Your Own Model
FlatRun does not ship a model. It talks to any OpenAI-compatible chat endpoint, so you can point it at OpenAI, a local runtime (Ollama, vLLM, LM Studio), or a compatible gateway.
| Setting | Meaning |
|---|---|
ai.enabled | Turns the feature on |
ai.base_url | API endpoint (defaults to https://api.openai.com/v1) |
ai.api_key | Token for the endpoint |
ai.model | Model name (e.g. gpt-4o-mini, llama3) |
ai.timeout | Per-request timeout (default 60s) |
Scopes
- System scope — ask about the whole instance: networking, health, configuration.
- Deployment scope — ask about one app. Here the assistant can also propose one-click actions validated against that deployment's services.
The Conversation Loop
- You open the assistant and ask a question.
- The model may call read-only tools to gather facts (list deployments, read logs, inspect config, run safe shell commands).
- It replies with an explanation, and on a deployment it may attach suggested actions.
- You can keep the conversation going with follow-up messages.
Auto-run vs. Approval
A toggle controls how tool calls run:
- Auto-run on — read-only tools execute automatically so answers come back in one step.
- Auto-run off — the assistant pauses and lists the tools it wants to run; you allow or decline each one.
What It Can and Cannot Do
The assistant's tools are read-only by design. Commands that would mutate state (anything matching rm, mv, chmod, delete, insert, update, reboot, and similar) are rejected before they run. Available tools include:
- Instance info, host network and Docker networks
- Deployment list, metadata, and recent logs (capped)
- Reading deployment files
- Running read-only commands on the host or inside a service container
Suggested Actions
On a deployment, the assistant can propose structured one-click actions instead of raw commands. Two kinds exist:
| Kind | Example |
|---|---|
| Service action | Restart, stop, rebuild, or pull a service |
| Exec | Run a specific command inside a named service |
Suggestions only target services that exist in the deployment's compose file, and each one runs only when you click it.
Secret Redaction
.env.flatrun) and system secrets (JWT secret, database
root password, Redis password, PowerDNS API key) are redacted out of logs and files before
they are sent to the model. The response reports how many values were redacted.
Even so, the assistant sends logs and config to whatever endpoint you configure. Point it at a provider you trust, or run a local model, when working with sensitive deployments.