Flue Guide

A TypeScript agent harness. Bring your own code; Maritime handles the runtime, persistence, and proxying.

Overview

Flue is an Apache-2.0 TypeScript framework for building agents that expose HTTP routes. It runs headless on Node.js — no chat gateway, no device pairing. Maritime ships it as a barebones runtime: the image gives you Node 20 plus @flue/cli, and a starter scaffold is seeded into /data/agent on first boot so the Chat panel works immediately.

Starter Scaffold

On first boot, Maritime drops these three files into your persistent volume at /data/agent:

/data/agent/
  package.json        # @flue/core + openai
  flue.config.ts      # defines one agent named "main"
  src/main.ts         # GET /, GET /health, POST /chat

Edit any of these files via the Coder tab; changes persist across restarts because /data is a Docker volume. The starter is only seeded when /data/agent is empty — so your edits never get overwritten.

How It Runs

The container boots flue dev --host 0.0.0.0 --port 3583, which watchessrc/ for changes and hot-reloads. Maritime publishes port 3583 and routes the dashboard Chat panel through POST /chat; webhooks and cron triggers can POST to any route you define.

Writing Your Own Agent

Replace src/main.ts with any Flue agent definition. The pattern is plain TypeScript:

import { defineAgent } from "@flue/core";

export default defineAgent({
  name: "main",
  routes: {
    "GET /health": () => ({ status: "ok" }),
    "POST /run": async (req: Request) => {
      const body = await req.json();
      // ... your agent logic
      return new Response(JSON.stringify({ ok: true }), {
        headers: { "content-type": "application/json" },
      });
    },
  },
});

Environment Variables

Maritime injects OPENAI_API_KEY andOPENAI_BASE_URL via its LLM proxy by default (no real key enters the container). Add your own env vars in the Settings tab — they show up in process.env inside the Flue process. SetFLUE_MODEL to override the starter's default (gpt-4o-mini).

Image

Stock node:20-slim. The entrypoint installs @flue/cli globally on first boot (~15s once, then cached on the host). Override via theFLUE_IMAGE backend env var if you want to pin a pre-baked image.

Deploy

Select Template → Flue Agent in the Create Agent modal, or:

maritime create -n my-flue-agent -t flue && maritime deploy my-flue-agent