OpenSteward

OpenSteward is a local-first agent orchestration workspace. It lets an operator define agents, execution configurations, durable documents/artifacts, reusable tools, and engine access for Codex, Claude, Gemini, Cursor, and local collector workflows.

The current app is a React/Vite client backed by the modular api/ service, PostgreSQL persistence, and the worker-api/ Docker execution runtime.

What Is Here

• Agent configuration UI for agents, executions, artifacts, tools, and engine setups.
• Runtime session UI for starting and monitoring agent work.
• Tool setup pages with stored server-side credentials and tool manuals.
• Portable sync bundles for moving local agents, sessions, documents, artifacts, and configuration into another OpenSteward environment.
• Admin/debug APIs for production monitoring without direct database or container access.

Local Development

The supported local stack uses the modular API and worker services from the root Compose file:

docker compose up -d --build

Then open:

• App: http://localhost:5173
• API: http://localhost:3010
• Worker API: http://localhost:3020

This starts:

• app: Vite client, proxied to api.
• api: modular API and PostgreSQL database.
• worker-api: worker API plus isolated Docker daemon for execution runs.

Useful commands:

docker compose restart api
docker compose logs -f api
docker compose down

If you run the modular API directly on the host while using the Compose database, set the database name explicitly:

$env:DATABASE_URL='postgres://opensteward:opensteward@localhost:55420/opensteward'
npm run dev:api

The full execution runner path is easiest through Compose because api talks to worker-api, which owns the isolated Docker runner.

Node Commands

npm install
npm run dev:client
npm run dev:api
npm run build
npm run test:run

npm run lint currently scans some non-app/generated areas too; prefer targeted lint while that is being cleaned up, for example:

npx eslint src/App.jsx src/lib/api.js

Important Environment Variables

• DATABASE_URL: PostgreSQL connection string. Compose sets this to the API database service.
• PORT: API port, defaults to 3000.
• VITE_API_PROXY_TARGET: Vite dev proxy target, defaults to http://127.0.0.1:3010; the Docker app service points at the Compose api service.
• OPENSTEWARD_API_RUNTIME_DIR: modular API runtime workspace directory, defaults to runtime.
• OPENSTEWARD_WORKER_API_URL: worker API URL used by api to dispatch executions.
• OPENSTEWARD_ADMIN_API_KEY: protects admin/operator routes.
• OPENSTEWARD_SYNC_API_KEY: protects sync import/export routes.
• OPENSTEWARD_SYNC_ALLOW_TOOL_SECRETS=1: allows sync export of tool secrets only when the request also opts in.
• OPENSTEWARD_PUBLIC_APP_URL and OPENSTEWARD_PUBLIC_API_URL: public URLs used by OAuth and setup flows.

Sync API

OpenSteward can export portable JSON sync bundles for moving local agent/session work into another OpenSteward environment.

• GET /api/sync/agents/:id/export exports an agent, its configuration, documents, and sessions.
• GET /api/sync/sessions/:id/export exports the owning agent configuration plus one session.
• POST /api/sync/import imports a bundle into the target environment, preserving UUIDs so repeated syncs update the same records.

Useful query parameters:

• include_sessions=false exports only agent configuration.
• session_ids=<uuid>,<uuid> limits an agent export to selected sessions.
• include_documents=false omits document file payloads.
• include_artifact_files=false omits artifact file payloads.
• dry_run=1 on import validates and summarizes the bundle without writing.

Set OPENSTEWARD_SYNC_API_KEY in the target environment to require an app-level key for all sync import/export routes. Clients can send it as either:

Authorization: Bearer <key>

or:

X-OpenSteward-Sync-Key: <key>

Tool credentials are redacted by default. To export stored tool secrets, both the request query include_tool_secrets=true and server environment variable OPENSTEWARD_SYNC_ALLOW_TOOL_SECRETS=1 must be set. Active local runtime state is made inert on import: running sessions become waiting_for_user, active execution runs become cancelled, and active generator sessions become stopped.

Standalone Agent Export

GET /api/v1/agents/:id/export returns a secret-redacted standalone runtime manifest for one agent. It is intended for runners outside the OpenSteward control plane, not for sync/import between OpenSteward environments. Run or inspect a manifest with npm run standalone:agent -- run --manifest agent.json --message "...". See docs/standalone-agent-export.md.

Use npm run standalone:agent -- bundle --agent-id <id> --out-dir ./agent-standalone to create a self-contained standalone agent folder for another repo. The bundle includes agent.json, the browser client, a local runner backend, Docker config, and SQLite session storage; it does not need OpenSteward or the OpenSteward API after export.

Tool Library API

OpenSteward can reuse agent-owned tools without sharing credentials between agents.

• GET /api/tool-library/tools searches tools across agents and returns source agent, linked execution context, run count, last-used time, source import type, and non-secret tool configuration.
• POST /api/tool-library/tools/:id/copy copies one tool into a target agent.

Useful query parameters for search:

• query=<text> matches tool name, source agent, type, env vars, description, and instructions.
• tool_kind=<kind> filters by tool type.
• agent_id=<uuid> limits results to one source agent.
• include_archived=1 includes archived tools.
• limit=<number> caps results, up to 120.

Copy request body:

{
  "target_agent_id": "<agent uuid>",
  "mode": "copy_configuration"
}

Use mode: "copy_configuration" to reuse install/setup/verify commands, instructions, env var names, JSON config, and source import rules. Use mode: "fresh_configuration" to create the same tool kind from defaults with new configuration. Stored token values, OAuth secrets, cookies, and browser state are never copied.

Admin API

Set OPENSTEWARD_ADMIN_API_KEY to protect operator/debug routes. If it is not set, OpenSteward falls back to OPENSTEWARD_SYNC_API_KEY; if neither key is set, admin routes are open for local development.

Clients can authenticate with:

Authorization: Bearer <key>

or:

X-OpenSteward-Admin-Key: <key>

The admin API is intentionally structured JSON rather than raw SQL:

• GET /api/admin/status returns app version, build/runtime settings, limits, and key configuration booleans.
• GET /api/admin/diagnostics returns DB/storage health, queue counts, engine setup state, recent errors, and recent admin audit events.
• POST /api/admin/diagnostics/run runs diagnostics and can refresh engine metadata.
• GET /api/admin/sessions/:id/debug returns the full session debug snapshot: config, messages, events, runs, artifacts, artifact versions, documents, evaluations, and checklist items.
• GET /api/admin/execution-runs lists runs with optional session_id, status, and limit filters.
• GET /api/admin/execution-runs/:id/debug returns one run with related session/config/events/artifacts/evaluations and optional include_logs=1.
• GET /api/admin/execution-runs/:id/logs returns runner logs.
• POST /api/admin/execution-runs/:id/cancel marks a non-terminal run as cancelled.
• POST /api/admin/execution-runs/:id/retry queues a retry using the same execution configuration.
• GET /api/admin/agents/:id/config returns the full agent configuration.
• PATCH /api/admin/agent-tools/:id updates a tool using the same payload shape as /api/agent-tools/:id.
• POST /api/admin/sessions/:id/context-document/refresh rebuilds session context documents.
• GET /api/admin/session-artifacts/:id/history and /download inspect artifacts.
• GET /api/admin/documents/:id/download downloads stored documents.

Admin mutations write to admin_audit_events.

Documentation Map

• docs/README.md: documentation entry point split into tutorials, how-to guides, reference, and understanding.
• docs/tutorials/: guided first-time paths for building, evaluating, repo-managing, and model-comparing agents.
• docs/how-to/: task-oriented guides for local runs, tools, executions, imports, standalone exports, debugging, and model changes.
• docs/reference/: technical contracts for source tree, API, data model, sessions, executions, artifacts, tools, definitions, evaluations, and standalone runtime.
• docs/understanding/: architecture explanations for lifecycle, managed/standalone, repo-managed agents, evaluations, and security.
• docs/new-agent-development.md: older single-page guide for building and maintaining agents.
• docs/agent-configuration-plan.md: current agent/execution/artifact configuration model.
• docs/agent-runtime-runner-plan.md: runtime and Docker runner design.
• docs/standalone-agent-export.md: standalone agent export manifest contract.
• docs/codex-engine.md, docs/claude-engine.md: engine setup notes.
• docs/gmail-oauth-tools.md: Gmail OAuth tool setup.
• docs/tool-manual-artifacts.md: durable tool manuals.
• docs/tekton-fluxcd.md: production build/deploy flow.