How Octomind cloud agents work

The 5-minute basics

Six ideas cover the whole product. Skim them once — everything else on this page is detail. And you don't need to be a developer: you tell an octo what you want in plain words, and it does the work.

• Octo — an agent for one thing you're working on: the blog, a client, your money. It keeps its own workspace, memory, conversations and routines, and hands work to specialist agents when that helps. Your first job makes your first octo; name more any time.
• Conversation — one thread with an octo. The transcript survives sleep and restarts, and its live cost is always on screen. One clear job per conversation works best.
• Machine — the computer in the cloud your octos work on. It's made for you and never needs your attention: an idle machine suspends itself, bills $0 compute, and wakes in seconds on the next message. Open Advanced only if you want to manage machines yourself.
• Models — every model is on every plan. Paid plans draw model usage from their allowance and then credits; Free has no allowance, so every call draws from prepaid credits. The model chip in an octo's header switches the conversation and becomes that octo's default — start with the default, escalate only when a job needs it.
• Caps — paid plans include a usage allowance for each billing period. Free has no allowance or refill; usage draws from prepaid credits and pauses when the balance is empty. A running machine pre-reserves its runway, so model calls can never eat a machine's budget — and you can never get a surprise bill.
• Keys — one hub key powers the CLI and any OpenAI-compatible tool; a developer key automates the whole cloud from code. Both live under Keys.

Overview

Three things make up your account:

• Octos — your agents, one per workstream, each with its own workspace, memory, conversations and routines.
• Machines — the long-lived containers (octomind + git + a terminal) your octos work on, placed for you. Several octos share one machine, each in its own folder.
• A wallet — a paid-plan allowance, when present, plus prepaid credits drawn down by usage.

Everything the agent needs (models, code indexing, memory) is wired up for you. You tune behaviour in Config and watch spend in Usage.

Octos

An octo is an agent with one job. Make one with ＋ New octo — a name is all it needs — or just ask on the home screen: the job goes to the octo you pick, else the one you used last, and your very first job makes your first octo. Each octo lives on one of your machines in its own folder, /home/octo/octos/<name>, so files, repos and notes from different jobs never mix; every conversation and routine of that octo runs in there. (The first octo on a machine works in the machine's home, /home/octo.)

New octos join the machine that already holds the most octos and still has room — a crew that shares one computer shares one compute bill — and a new machine is made only when none fits. A machine holds Small 5 · Medium 10 · Large 20 octos; your plan allows Pro 10 · Max 30 · Team 30 in total.

An octo's mark shows what it's doing, and the words beside it always say so too: working (a turn is running), idle (its machine is up and waiting), asleep (its machine is suspended — it wakes on the next message) and paused (the account reached its usage limit — top up or wait for the next period).

An octo's page puts the conversation on the left and everything about the octo on the right: Work (what it made and did, and its files), Routines, Can do (the chats that reach it, its instructions, the tools it can use) and Body (its machine, a shell in its folder, the sign-ins it holds, public endpoints). The ⋯ menu renames, recolours, saves its avatar or deletes it — deleting removes its folder, conversations and routines; the machine stays for its other octos.

Conversations & terminals

A conversation is one thread with an octo, running in the octo's folder on its machine. Its transcript is persisted to the shared directory, so it survives the machine suspending or being torn down — reopen it and the history replays. The picker in an octo's header lists its conversations; ＋ New conversation starts a fresh one with the same octo.

Every conversation runs as the cloud's orchestrator agent, which hands work to a specialist from the tap library when a job needs one — each reply says which specialist answered. It starts on the octo's model (or your plan's default); the model chip in the header switches it and makes it the octo's default, or type /model <name>. The same commands work from your chats and the Developer API message endpoint — /model, /effort, /info, /done, /plan, /schedule, /agents (argless shows current).

An octo's Shell opens a real terminal in its folder (as user octo). Detach it into the dock to keep it reachable on every page. Shells are ephemeral — they reset when the machine suspends — but conversations and files are always safe.

Conversations take attachments: paste or attach images (5 MB each, up to four per message) on any vision-capable model — on a text-only model the attach button disables itself and the tooltip names a model that works; nothing is ever silently dropped. Files land on the machine's own working disk under ~/.octomind/media, so the agent can open them and they show under Files; they cost nothing extra. Voice (paid plans): hold the mic and the transcript arrives in the composer as editable text — nothing sends until you press send. Replies can come back spoken in Telegram and WhatsApp, off until you enable it in Settings; transcription bills $0.010/min, speech $0.025/min, in the same Usage view as everything else.

Machines

Machines are the computers under your octos. You never have to create one — your first octo makes its own — but under Advanced you can create, size and manage them directly.

A machine is a persistent container built from one of three official images — Base (runtime, terminal, sudo, git, nvim, tmux, ast-grep), Default (adds Node, bun, a headless browser, ffmpeg and image tools — recommended for most work), and Programming (adds Python, PHP, Rust, Go, Node and build tools). Official images are free; you only pay for your own disk. Create a machine with three choices — name, image, size — and it provisions in seconds.

Every machine includes a real Docker Engine — docker build, compose stacks, testcontainers — on every cloud plan, isolated from the host by the sysbox runtime. Inner images and volumes live on the machine's working disk and count against its cap.

Install extra tools into your home directory (they persist and are hard-capped) with user-space managers like mise, cargo, uv or npm -g --prefix ~/.local. sudo works — apt included — but system-tree changes are not durable: they disappear when the machine is recreated. For system-wide packages you keep, build a custom image FROM muvon/octomind:<ver>-base, push it to a public registry, and add it under Images (Pro and up; we verify it derives from our base).

Machines move through a few states, which is what you pay (or don't) for:

Idle machines auto-suspend after a timeout you set per machine. A suspended box wakes automatically on a message to any of its octos, or when you open a shell — its working disk and shared directory are exactly as you left them.

Compute & working disk

Compute size (Small / Medium / Large — the sizes your plan allows) sets vCPU + RAM and is billed only while the machine runs. Working disk scales with the size, so a bigger machine can reserve a bigger disk.

Your fleet is bounded by machine slots: 1 slot = 1 vCPU (Small 1 · Medium 2 · Large 4), and every machine — suspended included — holds its slots until you delete it. Mix sizes any way that fits your plan's budget; the meter on the Machines page shows what's used.

Machines suspended for a few days move to cold archive storage: the machine keeps its slots and all its data, host resources are released, and the next start restores it onto any available cloud host — a few minutes instead of seconds. Extra disk above the included 10 GB bills a flat $0.04/GB-mo while archived (no premium tier), instead of the on-host $0.10–0.20.

Machines also reserve their projected runtime from your allowance: a running machine pre-claims a few hours of burn up front, so model calls can never eat a running machine's runway (the usage bars show this as a hatched "reserved" segment). If the allowance and credits can't fund a create or wake, it's refused with insufficient_usage; suspending or deleting a machine releases its reservation instantly.

Every machine includes 10 GB of working disk, free. Above that you reserve in steps at $0.10/GB-month, up to each size's bundle — Small 50 · Medium 80 · Large 160 GB. Need more? Stretch to double the bundle (Small 100 · Medium 160 · Large 320 GB), with the disk above the bundle billed at 2× ($0.20/GB-month). Disk is charged continuously in every state until you delete the machine — it holds your data whether the CPU is on or not. Delete the machine to stop paying; the shared directory survives.

You change disk on the create wizard and in a machine's Settings; the cost is previewed live.

Chat & GitHub connectors

Your octos answer where you already are — connect any of the four from Settings → Connections, included with every cloud plan (Pro, Max, Team). The contract is identical everywhere: plain text goes to an octo and the answer comes back in the same thread. A direct chat reaches the octo you chose with Send them here on its Can do tab, otherwise your most recent one; /octos, /use, /new and /model steer without opening a browser.

Group chats (Telegram, WhatsApp) each belong to one octo. Add the bot and send a message yourself: with one octo the group binds to it, with several you pick one (/use). Everyone's messages then reach that octo, but only you can run commands there (/help is open to all). Release on the octo's Can do tab frees the group again.

• Telegram — one-click connect to the official bot, or bring your own via @BotFather. Panel notifications mirror there (/mute to stop).
• Slack — installs into your own workspace; DM the app, commands ride /octomind (/octomind help).
• WhatsApp — link your number with one prefilled message and just talk; replies work within WhatsApp's 24 h conversation window.
• GitHub — install the app on your account or orgs, then mention it in any issue or PR comment: the thread becomes its own conversation and the answer lands as a comment. Machines also get repo access through it — git and gh just work via per-repo tokens that expire within the hour.

Every connector goes through the public API with your own credential — your allowance, plan limits and rate limits apply exactly as in the panel, and disconnecting is one button (or /unlink from the chat itself).

Workflows

A workflow runs a whole team of specialists on one input and hands you the finished result — the same multi-step pipelines the CLI's octomind workflow command runs, from the same tap library. Pick one under Advanced → Workflows, choose a machine, paste your full input, and start; a free dry run validates the pipeline on the machine first and shows every step before anything spends.

Steps light up live as they finish, loops show their passes, and the run keeps everything it printed in a downloadable full log. The final result renders at the end — and any files the run points at appear as artifacts you can download or preview right there.

Runs are one-shot: a finished, failed, or canceled run never resumes. The recovery is always a fresh run — Run again pre-fills the same workflow and input. Costs are the same meters as everything else: model calls through your hub key, compute while the machine runs; the run's total is shown for reference.

Routines

A routine is a job an octo runs on a schedule — every morning, every hour, whatever its cron expression says — in that octo's folder, without you opening a conversation. Create one on the octo's Routines tab or under Routines, save a finished conversation as one, or ask the octo to /schedule one. Each run is a real agent turn: the report is kept per run, and a notification tells you it finished — each routine carries its own notification preference, so an hourly check and a weekly report don't have to shout equally.

Routines are honest about not running: a tick that can't start (machine busy, allowance spent, paused) is recorded with its reason — a routine never silently skips. From Telegram, Slack or WhatsApp, /routines lists them, runs one immediately, pauses and resumes; completed runs deliver the full report into the chat. Times render in the routine's own timezone.

Public endpoints

An endpoint makes a service on your machine reachable from the internet at https://<token>.octomind.cloud — no deploy step, no tunnel tool. Claim one on a machine's page or under Endpoints: you're assigned a port from the machine's pool, and your app just binds 0.0.0.0:<port> (binding to 127.0.0.1 is the one classic mistake — the URL will tell you nothing is listening). There's no port number to type and nothing to get wrong.

New endpoints are private by default — only your account's signed-in users can open them — and you flip one public when you mean the whole internet. Disabling keeps the URL and the port; releasing retires the URL forever. An endpoint can also wake the machine on request if you enable that. Paid plans: 5 per machine, 5 / 20 / 50 across the account on Pro / Max / Team.

The agent can do all of this itself: every machine ships with a built-in cloud capability that talks to the cloud's MCP server, so "make me a landing page and give me a link" ends with the agent claiming an endpoint, starting the server detached, and handing you the live URL — through exactly the same plan limits and walls as the panel, never further. Endpoints are the first tool on that lane; more cloud powers arrive the same way, with nothing for you to configure.

Instructions (AGENTS.md)

An AGENTS.md is the opening context the agent loads into every conversation — what this environment is, where durable files live, how to behave. Your account's baseline lives under Configs → instructions and seeds every machine you create afterwards.

Every octo gets its own copy in its folder: that baseline plus who the octo is and what it's for. After that the file is the octo's — edit it on the octo's Can do tab (or in its shell); changes apply from the next conversation and survive restarts. The first octo on a machine uses the machine's own /home/octo/AGENTS.md, which Advanced also edits on the machine's Instructions tab. A repo with its own AGENTS.md uses that one while the agent works inside it, per the AGENTS.md standard.

Shared directory

Your shared directory is mounted into every machine at /home/octo/.local/share — exactly where octomind sessions, octocode indexes, and octobrain memory live, so everything that should outlive a single machine persists automatically. It survives machine deletes and ends only with your account.

It's included in your plan (Pro 20 · Max 60 · Team 100 GB) and billed by actual usage above that allowance at the same $0.10/GB-month as working disk — one disk rate across the whole product.

Models & keys

Every model call routes through octohub using one unified key that's injected into your machines automatically — you never paste provider API keys. Paid plans include model usage in their allowance; Free uses prepaid credits. See Models for the catalog and pricing.

Machines ship with the model set to octohub:auto: the hub picks the real model per call purpose — your conversation turns, the supervisor's checks, and context compression can each run a different model. Tune which model each purpose gets in Models → Auto model routing; rows you leave on default stay tuned by us. Pin a literal model id in your config only to opt out of routing entirely.

Your API keys are that same unified credential for use from the CLI or your own tools. Token spend is metered per call at the provider's price, drawing a paid-plan allowance first and then prepaid credits.

Use the hub from any tool

Your key isn't only for the cloud — octohub is an OpenAI-compatible gateway, so the same key works in any tool that speaks the OpenAI API: aider, Continue, Cursor, LiteLLM, LangChain, the OpenAI SDKs, or plain curl. Point the tool's base URL at the hub and pass your key as the bearer token.

• Base URL — https://hub.octomind.run/v1
• Auth — Authorization: Bearer <your key>, from API keys
• Model — a catalog id from Models (e.g. deepseek-v4.1-flash); set it explicitly. GET /v1/models lists the ids your key may call.

Chat completions — a drop-in OpenAI call:

curl https://hub.octomind.run/v1/chat/completions \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"Explain Rust in one sentence."}]}'

One key, two endpoints: /v1/chat/completions (classic OpenAI — the call above, for any tool) and /v1/completions (octohub's native Responses API with multi-turn chains and reasoning replay — what octomind itself uses). stream: true is accepted but the reply arrives all at once, re-framed as SSE — the first token comes no sooner. Calls made this way are metered like in-cloud usage: a paid-plan allowance first, then prepaid credits — one key, one bill, everywhere.

Developer API — agents from code

Everything the panel does is a REST API you can script — on every cloud plan. Create octos, run their conversations, read results: from CI, a cron job, or your own product. Base URL https://api.octomind.run/api/v1, auth Authorization: Bearer <developer key> — a developer key (om_…) created in API keys. None exist by default; hub gateway keys are a different credential and are rejected here. The machine-readable contract lives at GET /api/v1/openapi (no auth).

The whole loop, in four calls:

# 1. create an octo — its machine is picked (or made) for you;
#    the response carries its id and machine_id
curl -X POST https://api.octomind.run/api/v1/octos \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"name":"CI","about":"keeps the build green"}'

# 2. start a conversation with it AND its first turn in one call
curl -X POST https://api.octomind.run/api/v1/machines/<machine_id>/sessions \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"octo_id":"<octo id>","title":"fix build","message":"clone repo X and make the tests pass"}'

# 3. poll the turn (working=false = done); or add "wait_s":60 to the message call
curl "https://api.octomind.run/api/v1/sessions/<session id>/history?after=0" \
  -H "Authorization: Bearer <your key>"

# 4. job over — the octo, its folder, conversations and routines go; the
#    machine stays and sleeps for free when idle
curl -X DELETE https://api.octomind.run/api/v1/octos/<octo id> \
  -H "Authorization: Bearer <your key>"

Sending a message is async by default: the cloud holds the connection to the agent and streams the turn into stored history, you poll history?after=<cursor> until working flips false. Prefer push? Subscribe to the live event stream (SSE — works with curl -N, no WebSocket client needed):

curl -N "https://api.octomind.run/api/v1/sessions/<session id>/events" \
  -H "Authorization: Bearer <your key>"

Good to know:

• One driver per conversation — a second message while a turn runs returns 409 session_busy. The panel and the API share state live: a turn started from CI shows up here in real time, and vice versa.
• Suspended machines wake automatically on message (+$0.001 activation) — your script never has to manage machine state.
• Retries are safe — send an Idempotency-Key header on POSTs and the stored response is replayed for 24 h instead of double-creating.
• Rate limits (requests/min per key): Pro 180, Max 300, Team 600 — X-RateLimit-* headers on every response, 429 + Retry-After when exceeded. Usage itself draws your normal allowance; there is no per-request fee.
• Model concurrency (hub, in-flight requests per account — all your keys share one budget, completions and embeddings together): Free 1 on the $5 starter credit, 2 after any top-up, then 3, 4 and 5 once top-ups reach $20, $100 and $200 in total; Pro 3, Max 5, Team 15. At the limit a request queues up to 15 s, then returns 429 — reduce parallelism and retry.
• Teams — your member key acts on the team automatically: pooled wallet, your attribution, your per-member cap.
• Attachments ride two calls — upload the bytes first (POST /machines/:id/media with the raw file as the body, ?media_type=&name= in the query; ≤ 8 MB), then pass the returned ids as media_ids (up to 4) on POST /sessions/:id/message. Text may be empty when media is attached. Audio uploads come back already transcribed — the machine only ever receives text.

The whole public surface, by group:

Every response is [null, data] on success or ["e_code", details] on failure, with an honest HTTP status. Named errors worth handling: 409 session_busy, 429 rate_limited (+Retry-After), 409 limit_reached (octos for the plan, octos_per_machine for a full machine), 422 invalid_octo (an octo_id that isn't yours or lives on another machine), 402 member_capped, 503 session_runtime_unavailable, 422 invalid_wait/invalid_message/model_not_available (a /model switch to a model id not in the catalog, or retired), 422 too_many_attachments/attachment_not_found (a media_ids entry that isn't yours or isn't on that machine). Responses echo X-Request-Id — include it in support requests.

Configuration

You get your own editable configuration for all three tools — octomind (the agent), octocode (code search), and octobrain (memory). Start from the shipped default and tune what matters: the model per role, reasoning effort, context compression, the supervisor, indexing and search precision, memory decay.

Edit it the friendly way (a form with every parameter explained) or drop to raw TOML for full control, in Config. Whatever you save is injected into every machine you create or restart — so your tuning is your baseline everywhere. Model routing stays cloud-managed: you pick the model, the cloud handles the provider and keys.

Billing

Usage is metered across these line items, all drawn from one wallet:

• Tokens — per model call, at list price.
• Compute — vCPU + RAM per second while a machine runs (RAM only when idle).
• Conversation activation — $0.001 for each new conversation.
• Working disk — reserved GB above the 10 GB included, in every state, until delete.
• Shared storage — actual GB above your plan allowance.
• Bandwidth — egress is metered per account with 1 TB / month included, then $0.01/GB; incoming traffic is free. Best-effort speed (shared link). Most users never reach the allowance, so there's no bandwidth line on a normal bill.

Paid plans carry one usage allowance per monthly billing period. Free has no allowance and no refill: all usage draws directly from prepaid credits. Every model is billed the same way: what the provider charges us. On a paid plan, credits take over automatically when its allowance runs out; when neither allowance nor credits are available, model calls pause while your machine, files and history stay untouched. Everything itemised is in Usage.

Coupons: promo codes (they look like OCTO-…) redeem on the Billing page — free accounts only, once per code, and the credits land in the same wallet with the transaction attributed to the coupon. Codes come from campaigns, events, or a comeback email we may send with a personal code.

Invite & referrals

Every account has an invite link (Invite in the sidebar). Someone who signs up through it starts with +1 GB shared storage, permanently. When they run their first cloud task you earn +1 GB too — up to +25 GB, a permanent addition to your plan allowance. Storage comes with a cloud plan (Pro, Max, Team), so that is where both storage rewards apply. And if they ever subscribe, you both get the same one-time credit bonus: Pro $5 · Max $25 · Team $50, by their plan. Credits never expire.

Rewards are once per invited person; self-referrals don't count; a refund within 30 days reverses the credit bonus. Storage you earned always stays.