Quickstart

Open a project, choose a model, and inspect your first workbench result.

Start with a result you can check: explain a small project, then make one scoped change. Prepare a project copy you can modify and access to a model provider. Time and cost depend on the project and model.

Need a project? Use the three-file Parcel Notes sample. Follow its copy and initial-output steps, then return here to open the workbench. That guide contains the complete requests and 750 g → 800 g acceptance checks. Running the sample requires Node.js 22 or newer.

Open the workbench

Choose a package for your platform on the download page and follow the installation guide. With a desktop installer, launch OpenCorvus. With a complete command-line runtime package, run this from your prepared project directory:

opencorvus serve --hostname 127.0.0.1 --port 7878

Keep the terminal running and open the local workbench. Use the printed address if you choose another port. Source startup and API instructions are in the expandable section below.

Choose the project and model

Select your directory in the sidebar’s project area; use its create-project entry to add a directory on first use. For the sample, select the copied parcel-notes directory, not the whole OpenCorvus repository.
Start a new Chat for that project and select Code and Chat. Chat is a direct conversation; Mission supports ongoing orchestration. Use Chat for this exercise.
Open the model selector beside the message input. If no provider is configured, choose Configure Provider…, complete your provider’s connection setup, then return to select an available model. You can select an already configured model directly.

A model appearing in the list does not prove the connection works; check the actual response after sending. For environment variables or custom gateways, see the provider guide.

Send the first request

For Parcel Notes, send the sample guide’s first request. For your own small project, try:

Inspect this project and create docs/first-result.md. Explain its purpose, entry point, main modules, and existing start and test commands with exact source paths. Run suitable existing checks and record the observed results, or explain what prevented execution. Keep application source and tests unchanged. Distinguish facts from assumptions.

Follow progress in the same conversation. When permission is requested, read the specific action before deciding. If the model returns an error, resolve that connection error; work that did not execute is still incomplete.

Inspect and continue

Open docs/first-result.md in your project and compare its claims with the source and actual command results. For Parcel Notes, verify 750 g, then send the guide’s follow-up in the same Chat: change the third weight to 425 grams and check that the source, test and explanation all agree on 800 g. For your own project, choose a similarly small change with an explicit expected result.

Inspect actual files and differences even after the conversation reports completion. You can inspect a real Task’s output files to see what checkable delivery looks like. This is a maintainer Task sample record, not an execution report for this page’s Chat flow.

Whether you finish or get stuck, the trial feedback entry welcomes your version, operating system, model and concrete outcome. Keep credentials and private project content out of public feedback.

Optional: Task API

The following creates a separate Task for script or service integrations. Chat above sends messages directly in the workbench and does not require these HTTP commands.

Show model configuration, startup and Task request examples

1. Choose a model

Configure your provider using the provider guide. In the target project, create or edit .opencorvus/opencorvus.jsonc and set model to an exact provider/model identifier available to that provider:

{
  "model": "your-provider/your-model",
}

Replace the placeholder before starting. The credential must belong to the same provider and be available to the runtime. Keep it out of committed configuration. opencorvus models lists model identifiers; listing a model does not prove a live request will succeed. opencorvus doctor checks local platform capabilities.

2. Start the server

From the project directory, run:

opencorvus serve --hostname 127.0.0.1 --port 7878

Keep this terminal running. For a source checkout, use bun /absolute/path/to/opencorvus/packages/opencorvus/src/index.ts serve --hostname 127.0.0.1 --port 7878 from the target project. Use the address printed by the server if you choose another port.

Open the local workbench to inspect conversations and results. Choose the project, model and Expert Squad deliberately when creating work in the interface. The HTTP (Hypertext Transfer Protocol) examples below provide an alternative submission path.

These examples use a local server without a password. If you configured OPENCORVUS_SERVER_PASSWORD, add --user opencorvus to curl and enter the password at its prompt. In PowerShell, supply your configured Basic authentication credentials. See network configuration before exposing the service beyond localhost.

3. Submit a bounded Task

In a second terminal, change to the same project directory. The required fields are productPillar (code or work) and request. This example uses code because it inspects a repository. The configured model and active Expert Squad apply; use model or promptProfile in the request to select them explicitly.

Bash:

curl --fail-with-body -X POST http://127.0.0.1:7878/task \
  -H "content-type: application/json" \
  -H "x-opencorvus-directory: $PWD" \
  -d '{
    "productPillar": "code",
    "request": "Inspect this repository and create docs/architecture-overview.md. Explain the entry points, main modules, and available build or test commands with exact source paths. Verify those paths and distinguish facts from uncertainty. Do not modify application source."
  }'

PowerShell:

$projectDir = (Get-Location).Path
$headers = @{ "x-opencorvus-directory" = $projectDir }
$body = @{
  productPillar = "code"
  request = "Inspect this repository and create docs/architecture-overview.md. Explain the entry points, main modules, and available build or test commands with exact source paths. Verify those paths and distinguish facts from uncertainty. Do not modify application source."
} | ConvertTo-Json
$accepted = Invoke-RestMethod -Method Post `
  -Uri "http://127.0.0.1:7878/task" `
  -Headers $headers -ContentType "application/json" -Body $body
$taskId = $accepted.task_id
$accepted

HTTP 202 returns task_id, project_id and directory. Save these exact values. Acceptance means the request was admitted; it does not mean the deliverable is ready.

4. Observe progress

In Bash, set TASK_ID to the returned value:

TASK_ID='paste-the-returned-task-id'
curl --fail-with-body "http://127.0.0.1:7878/task/$TASK_ID"
curl --fail-with-body "http://127.0.0.1:7878/task/$TASK_ID/board"
curl -N "http://127.0.0.1:7878/task/$TASK_ID/events"

The last command keeps a Server-Sent Events (SSE) connection open. Press Ctrl+C to stop watching; this does not cancel the Task. The stream includes connection and progress events. After a disconnect, read the Task and board again before deciding whether work has stopped.

In PowerShell, inspect the same record and board, or follow the Task in the workbench:

Invoke-RestMethod "http://127.0.0.1:7878/task/$taskId"
Invoke-RestMethod "http://127.0.0.1:7878/task/$taskId/board"

5. Check the result and continue

Open docs/architecture-overview.md. Confirm the cited paths exist, the overview matches the repository, and any uncertainty or incomplete work is explicit. Inspect the Task’s changes and evidence in the workbench. A terminal status alone is not proof that these conditions were met.

For a correction, send ordinary follow-up input to the same Task:

curl --fail-with-body -X POST "http://127.0.0.1:7878/task/$TASK_ID/message" \
  -H "content-type: application/json" \
  -H "x-opencorvus-directory: $PWD" \
  -d '{"text":"Check the overview against the source again and add any missing entry-point paths.","source":"api"}'

$followUp = @{
  text = "Check the overview against the source again and add any missing entry-point paths."
  source = "api"
} | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri "http://127.0.0.1:7878/task/$taskId/message" `
  -Headers $headers -ContentType "application/json" -Body $followUp

A terminal Task can reopen on accepted new input while retaining its history and fixed Expert Squad. Read the response and refreshed Task state; an accepted message is not a completed correction.

When you get stuck

Creation returns an error: read the response body. Confirm both required fields, the exact project directory, selected model and available Expert Squad.
Model request fails: inspect the reported provider/model error and provider configuration. Local doctor success does not validate credentials or model access.
Permission is waiting: inspect the pending request in the workbench and decide whether to allow or deny it. See permissions.
The result is incomplete: send the specific missing requirement to the Task and inspect the next result.

Continue with the Mission and Task API for integration details, Slack for channel setup, or troubleshooting for diagnosis.