Arctic Base

Arctic Base

A self-hosted workbench host for AI agents. Decisions, file handoff, document review, and async signaling — out of band from chat, with a real audit trail.

v1 — pilot ready 61 backend tests FastAPI · Svelte 5 MIT license
// SYSTEM_OVERVIEW

What it is

Arctic Base is the layer that sits between you and your AI coding agent for everything that doesn't fit in chat. The agent uses an HTTP API to publish approval forms, drop files, share images, render markdown, and ask questions; you respond in a browser at your pace. Each project gets its own themed workbench — visually distinct, persistent, auditable.

7
Object kinds
4
Templates
7
Layout tokens
68
Backend tests
// ARCHITECTURE

How it's wired

Single FastAPI process. Static SPA mounted at the root. State lives in flat files behind a Storage protocol. The agent's surface and the user's surface share the same origin — no CORS, no auth ceremony.

// AGENT Claude Code or any HTTP client // USER Browser desktop or mobile // FASTAPI :: SAME ORIGIN AGENT API /agent /api/agent/* conv. · templ. · activity WORKBENCH API /api/workbenches …/objects · …/responses CRUD · render · poll SVELTE SPA :: STATIC ASSETS / /settings /blueprints /wb/{slug}/... window.workbench bridge ↔ themed iframes // STORAGE Filesystem data/workbenches/ {slug}/ manifest.json theme.md objects/{id}/ responses/{id}/ SQLite-swappable behind Protocol HTTP / HTTP flat files
// FEATURES

What's in the box

Self-contained HTML

Approval / Q&A / pitch templates. Reference --wb-* CSS vars, fall back to localStorage + JSON export. Open standalone or via the workbench.

Polling that scales

?since_version=N — agent polls 2–5 s while waiting; submit() bumps the version and wakes the loop. Long-poll / SSE upgradeable, no contract churn.

Per-workbench identity

Theme tokens drive colors, typography, spacing — and a 7-axis layout block for density, corners, shadows, motifs, banner shape. Same template, five visibly different feels.

Stale-check editing

UI editor sends If-Match; if the agent rewrote the file underneath, you get a 412 with a "reload / overwrite / merge" prompt. Agent writes always succeed.

Activity timeline

Every API call lands in an in-memory ring buffer; surfaced as a CRT terminal at the top of the management page. Polls every 5 s. Status colored by code.

Custom fields

Add arbitrary key: value pairs to a workbench: deploy_cmd, ci_url, secrets_path. Visible to agents on the manifest, rendered on the dashboard.

Runbook kind

Persistent JSON task list. Steps with status (todo/in-progress/done/blocked), per-step blockers, and timestamps. Agent reads + writes via GET/PUT .../content; user ticks checkboxes in the browser. Survives across sessions.

Pin & archive

Pin objects to the top of their drawer; archive to hide without losing them. Toggle "Show archived" on the workbench dashboard. Edit-mode reveals reorder + delete + pin + archive controls.

Image paste / drop

Paste a clipboard image or drag a file into the MD or HTML editor — it uploads as a real kind: image object and inserts the link at the cursor. No "save → find → drag" friction.

Snapshots

Labelled tar.gz checkpoints — proactive backup before risky agent runs. List, download, restore-into-new-workbench, delete. Different from trash (reactive); this is "save before letting the agent run wild."

Audit log

Chronological NDJSON of every content-level mutation: object create / update / delete / content-write, theme writes, response appends, workbench updates. Per-workbench download. Replay history without spelunking the filesystem.

Static-site export

One-click zip of a workbench: rendered MD, themed approval HTML, images, files, theme CSS, index page. No Arctic Base required to view — host on any static server. Good for archival.

Agent self-test

POST /api/agent/self-test — synthetic round-trip in milliseconds. Confirms the loop works (workbench create → object → content → response → read → cleanup) before the agent commits to a real task. Catches deploy bugs early.

// AGENT_WORKFLOW

How an agent uses it

Hand the agent one URL — /agent — and the chain of auto-discovery does the rest.

  1. agent GET /agent → 302 to /openapi.json
    Cheapest entry point. Agent now knows every endpoint shape.
  2. agent GET /api/agent/conventions
    ~8 KB markdown of what OpenAPI can't express: window.workbench contract, polling cadence, theme tokens, review-HTML rules, template-first authoring discipline.
  3. agent POST /api/agent/bootstrap {project_title}
    Creates the workbench in one call. Returns a checklist (theme? banner? local_path? tags? CLAUDE.md snippet?) for the agent to walk you through.
  4. agent GET /api/agent/templates/approval-questions?fill_title=…
    Fetches a self-contained HTML starter with {{TITLE}} / {{STATE_KEY}} pre-filled. Agent edits the marked QS array.
  5. agent POST /api/workbenches/{slug}/objects
    Multipart with meta JSON + file body. Object lands in the "approvals" drawer of the workbench dashboard.
  6. user Opens browser
    Reviews the question set in their themed workbench, picks options, leaves notes, hits Submit.
  7. user window.workbench.submit(state)
    localStorage cached, mirrored to API, state_version bumps from 0 to 1.
  8. agent GET …/responses/latest/payload
    Raw JSON the user sent. Agent acts on it. Loop closed.
// THEMING_AS_LAYOUT

Theme drives more than color

Each workbench has a theme.md with structured tokens (colors / typography / spacing) and a layout block that controls composition: density, corner style, shadow style, card decoration, banner shape. Same Svelte template, visibly different output.

KND Treehouse
compact · sharp · bolted · hard-offset
Forge Parchment
spacious · soft · floating · soft-shadow
ARA Codex
comfortable · rounded · floating · glow + hex
Muzzy Arcade
compact · sharp · bolted · tape + crt-monitor
Red X · Xenothium
compact · sharp · inset · glow + t-shape
// API_HIGHLIGHTS

Agent-facing endpoints

Just the ones agents care about. Full machine-readable spec at /openapi.json.

METHODPATHWHY
GET/agent302 → /openapi.json. Single URL to hand any agent.
GET/api/agent/conventions≈8 KB runbook for things OpenAPI can't express.
POST/api/agent/bootstrapCreate workbench + return follow-up checklist.
GET/api/agent/templates[/{id}]List templates / fetch with ?fill_title=....
GET/api/agent/claude-md-snippet?slug=Paste-ready CLAUDE.md / AGENTS.md fragment.
GET/api/agent/activityRecent API calls (in-memory ring buffer).
POST/api/workbenches/{slug}/objectsCreate object (JSON or multipart).
PUT…/objects/{id}/contentWrite content. If-Match for editor stale-check.
GET…/responses?since_version=NPolling endpoint. Returns events newer than N.
GET…/responses/latest/payloadBare JSON the user submitted.