Skip to content

getting-started.md

Latest commit

 

History

History
288 lines (192 loc) · 10.1 KB

getting-started.md

File metadata and controls

288 lines (192 loc) · 10.1 KB

Oversight -- Quick Start Guide

This guide walks you through installing Oversight, launching the server, and running your first AI agent on a task.

1. System Requirements

Requirement Minimum Version Notes
Rust 1.75+ Install via rustup
Node.js 20+ Required to build the web frontend
pnpm 8+ npm install -g pnpm
Git 2.30+ Worktree support required

Optional:

  • PostgreSQL 15+ -- only if you choose the pg storage backend.
  • Claude Code, Codex, or OpenClaw CLI -- only if you plan to use CLI-based agents.

2. Installation

Clone and build from source

git clone https://github.com/aspect-build/oversight.git
cd oversight

# Build all binaries (server, CLI, worker)
cargo build --release

The compiled binaries will be at:

  • target/release/oversight-server
  • target/release/oversight (CLI)
  • target/release/oversight-worker

Build the web frontend

cd web
pnpm install
pnpm build
cd ..

The frontend assets are output to web/dist/ and the server serves them automatically.

3. Generate an Encryption Key

Oversight encrypts sensitive data at rest. Before first launch, generate a master key:

./target/release/oversight-server genkey

This prints a base64-encoded key to stdout. Export it as an environment variable:

export OVERSIGHT_MASTER_KEY="<paste the key here>"

Keep this key safe. You will need it every time you start the server.

4. Start the Server

With default settings (SQLite storage, port 7878):

./target/release/oversight-server

Or during development, using cargo:

cargo run -p oversight-server

You should see log output similar to:

INFO oversight_server: observability enabled  metrics_endpoint="/metrics" health_endpoint="/health"
INFO oversight_server: ensuring default project, workflows and agent definitions
INFO oversight_server: listening on 127.0.0.1:7878

Common environment variables

Variable Default Purpose
OVERSIGHT_PORT 7878 HTTP server port
OVERSIGHT_HOST 127.0.0.1 Bind address
OVERSIGHT_DATA_DIR .oversight Directory for database and files
OVERSIGHT_STORAGE sqlite Backend: sqlite, pg, or fs
OVERSIGHT_EXPERIMENTAL_MIXED_STORAGE (disabled) Required for server startup with OVERSIGHT_STORAGE=pg or fs
OVERSIGHT_MASTER_KEY (none) Encryption master key
OVERSIGHT_API_TOKEN (none) Optional API authentication token
OVERSIGHT_STATIC_DIR web/dist Path to frontend build output

sqlite is the default production server backend today. When you choose pg or fs, startup also requires OVERSIGHT_EXPERIMENTAL_MIXED_STORAGE=1 because some runtime/auth/mailbox paths still keep local state under OVERSIGHT_DATA_DIR.

See the Configuration Reference for the full configuration reference.

5. Open the Web UI

Navigate to http://localhost:7878 in your browser.

On your first visit, you will see the admin account setup screen:

Admin Setup

Create an admin username and password, then click Create admin.

6. First-Run Wizard

On your first visit, a setup wizard appears with three steps:

Step 1 -- Project

Enter a project name (e.g., "My App") and an optional one-line description. The project is the top-level container for all your tasks, workflows, and documents.

Step 2 -- Workflow Template

Choose how tasks flow from creation to completion:

Template States
Agile / Scrum Backlog -> Sprint Ready -> In Progress -> Review -> Done
Requirements (V-Model) Draft -> Analyzing -> Approved -> Implemented -> Verifying -> Verified
Kanban Todo -> Doing -> Done
Blank No workflow -- configure later from Settings

Pick the template that fits your process. You can modify states and transitions later from Settings -> Workflows.

Step 3 -- Seed Task

Optionally create a sample task called "Welcome -- try running an agent." This lets you immediately explore the task detail view, activity log, and agent chat. You can delete it later.

Click Create & open to finish. Your project dashboard appears.

Recommended first flow

The fastest way to understand Oversight is not to start from a blank task. Start from a document that should drive execution:

  1. Open Settings → Planning.
  2. Create or choose a planning knowledge base such as Plans & SOPs.
  3. Write a short requirement, rollout plan, or SOP.
  4. Create the linked execution task from that document.
  5. Open the task and assign users or agents, request decomposition, and continue work from there.

This reflects the core product model:

  • documents hold intent
  • tasks hold execution
  • task-bound threads hold live discussion and agent runs

7. Connect a CLI Agent

Oversight orchestrates CLI-based AI agents (Claude Code, Codex, OpenClaw) through its unified Agent Client Protocol (ACP) bridge.

Before using this flow, make sure the underlying agent CLI is both:

  • installed on your machine, and
  • already signed in / authenticated with its own provider (codex login, Claude auth, Hermes/OpenClaw auth, etc.).

Initialize the integration

From your project directory:

# For Claude Code
./target/release/oversight init --agent claude

# For Codex
./target/release/oversight init --agent codex

# For OpenClaw (Hermes)
./target/release/oversight init --agent hermes

This creates agent-specific configuration:

  • Claude: .claude/settings.json with MCP server + CLAUDE.md integration section
  • Codex: Codex MCP configuration
  • Hermes: .hermes/system_prompt.md

If you already logged in to Oversight with oversight auth login --server ... or switched to a named profile, oversight init will reuse that active server automatically. Otherwise it falls back to http://localhost:7878.

Run an agent on a task

# Interactive session -- creates a new task and assigns Claude
./target/release/oversight run claude --title "Implement login page"

# Bind to an existing task by ID
./target/release/oversight run claude --task TASK-abc123

# Use a server-side agent definition for full config
./target/release/oversight run claude --task TASK-abc123 --agent-def coder

# Headless mode (non-interactive, single-shot)
./target/release/oversight run claude \
  --title "Fix the navbar" \
  --prompt "The navbar overflows on mobile. Fix the CSS."

The agent will:

  1. Connect to the Oversight server via MCP.
  2. Bind to the specified task.
  3. Create an isolated git worktree for the work (unless --no-worktree is passed).
  4. Execute with full access to Oversight tools (tasks, documents, knowledge base).

Because runs are task-bound, the resulting conversation, run log, and produced artifacts stay attached to that task instead of floating in a separate chat silo.

Local mode (unbound runs need no server)

The CLI can also help with purely local sessions, but there is an important distinction:

  • oversight init is always local.
  • oversight run without --task / --title can be used as an unbound local session.
  • oversight run --task ... and oversight run --title ... require a reachable Oversight server because they bind to real tasks.
  • Even in headless mode, the underlying agent CLI must already be authenticated; Oversight handles task binding + MCP wiring, while the agent CLI still talks to its own provider.
# Initialize locally
./target/release/oversight init --agent claude

# Unbound local session
./target/release/oversight run claude --prompt "Audit the parser for edge cases." --no-worktree

# Task-bound run (requires a reachable server)
./target/release/oversight run claude --title "Add tests" --no-worktree

Local state files are stored in .oversight/:

  • task-context.md -- written for task-bound runs
  • project-resources.md -- written when project resources are resolved from the server

CLI reference

Flag Description
--task <ID> Bind to an existing task by ID
--title <str> Create a new server-backed task with this title
--server <url> Oversight server URL (default: http://localhost:7878)
--agent-id <id> Agent identity for MCP auth (default: developer)
--agent-def <id> Use a server-side agent definition for full config
--prompt <str> Run headless with this prompt (non-interactive)
--no-worktree Skip git worktree creation
--git-author Git author name for commits
--git-email Git author email for commits

8. Verify the Setup

Check that everything is running:

  • Health check: curl http://localhost:7878/health
  • Metrics: curl http://localhost:7878/metrics
  • API: curl http://localhost:7878/api/tasks

9. What's Next

You now have a running Oversight instance with a project, workflow, and (optionally) a connected CLI agent.

To go deeper: