How Oktapod works
The pieces that make up your agent, what happens when you ask for something, and why it can be trusted with real work.
This page explains Oktapod without assuming you write code. For the component map and technical rules, see Architecture.
The pieces
Oktapod is one agent with several ways in.
| Piece | What it does |
|---|---|
| Core | The agent itself. It plans, checks policy, runs actions, asks for approvals, keeps memory, runs schedules, and records everything. It runs as a background service. |
| Gateway | The private front door. The web app, phone apps, and messaging channels all reach the core through it, and it checks your access key or Tailscale identity. |
| Database | SQLite on your machine, with vector search for memory. Conversations, memory, approvals, schedules, and receipts all live here. |
| Apps | The web app, the iPhone and Android apps, the Mac app, and the oktapod command. They are windows onto the same agent, not separate assistants. |
| Channels | Messaging apps such as Telegram or WhatsApp. They carry messages in and out; they do not make decisions. |
| Models | The AI service you connect, such as ChatGPT, Claude, Gemini, or a local model. The model reasons; the core decides what is allowed to happen. |
Because every surface talks to the same core, a conversation started on your phone, an approval given in the browser, and a schedule created from the terminal all end up in one place.
What happens when you ask for something
-
Intake
Your message arrives from any app or channel and is tied to a conversation.
-
Understand and plan
The core asks the model what you mean and what steps are needed. It picks a fast, balanced, or deep model for each step based on how hard the task is, and records that choice.
-
Check policy
Each step is checked against policy: what it touches, how risky it is, and whether you already allowed it.
-
Ask when needed
Reading and answering run on their own. Steps that change something outside Oktapod, such as sending an email or editing a file, wait for your approval. The approval card shows what will happen and where.
-
Act
Approved steps run through connected apps, tools, or coding sessions. Retries reuse the same identity, so a network hiccup does not repeat a change that already happened.
-
Record the receipt
The run is saved as input, decision, action, and outcome. Useful facts can become memory, with a link back to their source.
Work that continues without you
Some work is not a single reply:
- Goals and tasks stay open until they are finished, stopped, or fail. See Goals, tasks, and schedules.
- Schedules wake the agent at the right time, even when every app is closed.
- Background upkeep runs on a timer inside the core. It retries queued work, processes uploads, cleans up old records, and checks connections.
Background work follows the same rules as chat. It never inherits an approval from an unrelated conversation, and risky steps still stop and wait for you.
Why it can be trusted
Oktapod is designed around a few rules that do not change:
- Every side effect has a receipt. You can see what was asked, why it was allowed, what ran, and what changed.
- Retries are safe. Every change carries an identity, so an automatic retry after a failure does not repeat an effect that already happened.
- Risky actions ask first. There is no global "allow everything" switch. Short, narrow exceptions exist, and they expire. See Approvals and safety.
- Memory has provenance. Each memory records where it came from, how confident it is, and how long it should be kept. See Memory and personality.
- Your data stays with you. By default Oktapod sends nothing to its developer. Your messages go to the AI service you connected and to the apps you asked it to use. See Privacy and your data.
Where things live
On the computer that runs Oktapod (macOS and Linux defaults shown):
~/.oktapod/oktapod.jsonholds settings.~/.oktapod/data/holds the databases, uploaded files, credentials, and backups.~/.oktapod/logs/holds service logs.
Credentials are kept in owner-only files, separate from normal settings, and are never shown back in chat.