Control Plane API

The kernel serves the control plane at /_seed and its JSON API at /_seed/api. Everything outside /_seed is reverse-proxied to the running organism.

Every endpoint except the logo needs X-Seed-Token (or ?token= for the event stream): the API token embedded in the control-plane page of a signed-in browser, or the CLI's token from .seed/control-token. Sign-in itself happens at GET /_seed/login?code= (a one-time link; it sets the session cookie and redirects to /_seed/).

All responses are JSON. Errors are {"error": "message"} with a non-2xx status. Timestamps are RFC 3339 strings.

Types

type Identity = {
  name: string;                    // display name the Seed currently goes by ("Seed" until it becomes something)
  tagline: string;
  accent: string;                  // CSS color, e.g. "#3b82f6" ("" = default)
  logo_url: string;                // "/_seed/api/identity/logo?v=<hash>" (SVG; changes when the logo changes)
};

type Status = {
  name: string;                    // technical slug from seed.yaml (stable)
  identity: Identity;              // who the Seed currently is — evolves with generations
  purpose: string;                 // "" while the Seed has no purpose yet
  generation: Generation | null;   // current generation
  organism: { state: "stopped" | "building" | "starting" | "running" | "failed"; error?: string };
  model: { provider: string; name: string; configured: boolean };
  active_evolution: Evolution | null;
  pending_approvals: number;
};

type Message = {
  id: string;
  conversation_id: string;
  role: "user" | "seed" | "system";
  content: string;                  // markdown
  evolution_id?: string;            // set when the message announces/tracks an evolution
  kind: "chat" | "report";          // report = written by the kernel about an evolution
  created_at: string;
};

type EvolutionStatus =
  | "requested" | "planning" | "planned" | "mutating" | "building" | "testing"
  | "running" | "observing" | "reflecting" | "ready" | "applying" | "complete"
  | "failed" | "needs_input" | "cancelled" | "rolled_back";

type Plan = {
  title: string;
  scope: string;                    // short slug, e.g. "tasks"
  summary: string;
  steps: { title: string; detail?: string }[];
  capabilities: string[];           // capabilities the Seed will have afterwards
  risks: string[];
  // Staging (absent for single-step evolutions): the owner's whole goal, the
  // full ordered roadmap, and the 1-based stage this evolution builds.
  goal?: string;
  stages?: { title: string; summary?: string }[];
  stage?: number;
};

type Question = { question: string; why?: string; options?: string[] };  // options: suggested answers, recommended first
type Clarification = { questions: Question[]; answer: string };

type Check = {
  name: string;                     // build | migrate | test | launch | health | http:<path>
  ok: boolean;
  detail: string;                   // short human-readable result
  attempt: number;
  tests_passed?: number;
  tests_failed?: number;
};

type Reflection = {
  summary: string;
  goal_satisfied: boolean;
  gaps?: string[];                  // when not fully satisfied: what falls short, and why
  decisions: string[];
  learnings: string[];
  skills: string[];                 // skills created or improved
  debt: string[];
};

type Evolution = {
  id: string;                       // evo_...
  intent: string;
  title: string;
  status: EvolutionStatus;
  plan: Plan | null;
  base_generation: number;
  new_generation?: number;
  branch: string;
  commit?: string;
  attempts: number;
  checks: Check[];
  reflection: Reflection | null;
  summary?: string;                 // what the builder says it did
  error?: string;
  kind: "evolve" | "rollback";
  questions?: Question[];           // set while status is "needs_input" because the Seed asked its owner
  clarifications?: Clarification[]; // earlier question/answer rounds
  created_at: string;
  updated_at: string;
  completed_at?: string;
};

type EvolutionEvent = {
  id: number;
  evolution_id: string;
  kind: "phase" | "plan" | "tool_call" | "tool_result" | "check" | "note" | "error" | "approval" | "agent_text" | "question";
  summary: string;                  // one line, suitable for a progress list
  data: any;                        // details (tool input/output, etc.)
  created_at: string;
};

type Generation = {
  number: number;
  title: string;
  intent: string;
  evolution_id?: string;
  commit: string;
  parent_commit?: string;
  current: boolean;
  tests_passed?: number;
  build_ok?: boolean;
  health_ok?: boolean;
  created_at: string;
};

type Approval = {
  id: string;
  evolution_id?: string;
  action: string;                   // e.g. "write_file kernel/agent/loop.go"
  level: "safe" | "review" | "dangerous";
  detail: string;
  status: "pending" | "approved" | "denied";
  created_at: string;
};

type Skill = { name: string; description: string; path: string; files: string[]; content?: string };

Endpoints

Live events

GET /_seed/api/events is a Server-Sent Events stream. Each event has an event: name and JSON data:.

Model ("mind") configuration

A Seed stores no credentials. The owner passes secrets as key/value pairs when starting it (seed run -e OPENROUTER_API_KEY, --env-file); a deployed Seed gets the same variables from its platform. The kernel holds them in memory only. If no key was passed, the owner may paste one in the control plane for this session only (memory; gone on restart). Keys are never returned by the API. The model choice (not a secret) is kept in the Seed's memory, and SEED_MODEL can also be passed at start. When a key is present and no model was chosen, the provider's default model is used.

type ProviderInfo = {
  id: string;                      // v0.1: "openrouter" only
  label: string;
  has_key: boolean;                // a key is available right now
  key_source: "env" | "session" | "";   // passed at start, pasted this session, or none
  key_env: string;                 // the variable to pass, e.g. "OPENROUTER_API_KEY"
  needs_key: boolean;
  needs_base_url: boolean;
  base_url: string;
  default_model: string;
  keys_url?: string;               // where to get a key
};

type ModelConfig = {
  provider: string;                // selected provider id
  name: string;                    // selected model id (the default when none was chosen)
  configured: boolean;             // the Seed can think (a key is present)
  providers: ProviderInfo[];
};

type ModelOption = { id: string; name: string; context_length?: number; description?: string };

Status.model ({provider, name, configured}) reflects changes; a status SSE event is sent after a change.

Edit this page on GitHub