Flue

import { serveOC } from '@opencomputer/flue';
import agent from './agents/support-triage.ts';

serveOC(agent);

​

Quickstart

git clone https://github.com/diggerhq/oc-flue-starter && cd oc-flue-starter
npm install

# create the agent (optional — `oc agent deploy` creates it from agent.toml if missing)
oc agent create support-triage --runtime flue --model anthropic/claude-sonnet-5

# build + upload + boot-verify + activate a revision
oc agent deploy

# talk to it
oc session create --input "Customer says order 1042 hasn't arrived — what do I tell them?"
oc session logs <session-id>

​

Add to an existing Flue app

npm install @opencomputer/flue

import { serveOC } from '@opencomputer/flue';
import agent from './agents/your-agent.ts';

serveOC(agent);

name  = "your-agent"                    # the OpenComputer agent name
model = "anthropic/claude-sonnet-5"     # must equal the model in defineAgent

[runtime]
family = "flue"

​

What changes vs a stock Flue app

​

What @opencomputer/flue does

• Conversation persistence. Opens Flue’s conversation store on the session’s state volume. History survives process restarts, hibernation, and machine moves. A db.ts is rejected at build because a second store would fork the conversation history.
• Sandbox. Flue’s built-in read/write/edit/bash/grep/glob tools execute on the session’s workspace sandbox — a separate machine from your app process, where attached repos are checked out. Custom defineTool code runs in-process with your app (see the network-access note below).
• Two added tools. say posts a message to the user mid-run. ask asks a question: the session yields needs_input and hibernates until the user replies, then the run continues with the answer.
• Model credentials. Registers the Anthropic provider with credentials resolved from the platform — managed metering or your key. The bundle and repo contain no credentials.
• Turn handling. Each session turn is admitted into Flue’s engine with an idempotent id, so platform-level retries can’t double-run it. If the platform side of a turn dies mid-run, the retry re-attaches to the still-running engine and streams from where it left off — the model call is not repeated. Every step — model text, custom tool calls, sandbox operations — is written to the session’s event log.
• Retries and timeouts. Flue’s durability settings are overridden: one engine attempt per turn, with the timeout set to the platform’s turn deadline. Cancel, retry, and deadline behavior is the platform’s; there is no second layer to reason about.

​

Custom tools

import { defineTool } from '@flue/runtime';
import * as v from 'valibot';
import orders from '../data/orders.json' with { type: 'json' };

export const lookupOrder = defineTool({
  name: 'lookup_order',
  description: 'Look up an order by id.',
  input: v.object({ order_id: v.string() }),
  run({ input }) {
    return (orders as Record<string, unknown>)[input.order_id] ?? { found: false };
  },
});

• Anything a tool needs at run time must be bundled — import fixture data and templates (as above); the repo checkout is not on the app’s filesystem.
• Outbound network: custom tools currently have unrestricted outbound access from your app’s process — where defineTool code runs, a separate machine from the workspace sandbox. An egress policy is planned; until it exists, don’t embed secrets in the bundle to call your own APIs — prefer self-contained tools.

​

Skills

​

Models

​

Limitations vs full Flue

• Channels (Slack, Discord, web ingress) don’t run here — inbound is session messages and GitHub watches. A full app keeps its channels when self-hosting; code not imported by src/opencomputer.ts never enters the artifact.
• Workflows (defineWorkflow) don’t run here; a workflow admission throws at run time.
• One agent, one conversation per session. serveOC(agent) hosts one top-level agent, and a session is one conversation instance — Flue’s per-instance routing has no equivalent; fan out by creating sessions.
• Subagents (session.task()) bundle and execute in-process, but they are outside the tested profile: their model declarations aren’t validated the way the top-level agent’s is, and subagent steps may appear incompletely in the session event log.
• Anthropic models only. Flue itself supports other providers (OpenAI, Google, …); on OpenComputer there is no credential source for them yet.
• durability settings are ignored. The platform pins one engine attempt per turn under the turn deadline; retry and timeout policy is the platform’s. Setting durability: in defineAgent has no effect.
• Text in, text out. Sessions exchange text; there is no way to send the agent an image or a file attachment.
• No HTTP endpoints. A Flue app’s own server doesn’t run; requests reach the agent only through the sessions API.

​

Deploying

​

Troubleshooting

• Build fails (oc-flue-build) — a profile violation, named in the error: sandbox: set, a db.ts, a packaged-skill import, a reserved tool name, or a model that isn’t anthropic/…. Nothing is uploaded.
• Deploy fails at verification — the bundle built but didn’t boot in the scratch sandbox; the deploy output carries the probe error. Usual cause: a top-level crash in your code (something that only happens at import time).
• Model rejected at deploy — the three model declarations diverge (defineAgent, agent.toml, the OC agent).
• provider 401 on the first turn — no usable model credential. Managed billing is the default, so this usually means the org’s billing isn’t set up yet — set up billing, or attach a valid Anthropic credential to the agent.
• Skill not loading — the agent’s own skills go in src/skills/<name>/SKILL.md; skills from a codebase require that repo attached as a session source (--source).