API server

harbor serve runs jobs and manages sandboxes. Clients connect to the same server and see the same jobs; execution continues when a client disconnects.

Start the server

With Docker running, start the server:

harbor serve

Leave HARBOR_API_KEY unset for this local example. The examples below use the public hello-world task and the oracle agent, which runs its reference solution. No Hub or model API key is needed.

Use Daytona instead of Docker

Configure the sandbox provider on the server, then use "environment": {"type": "daytona"} in your job config, or --env daytona in the CLI.

uv pip install "harbor[daytona]"
export DAYTONA_API_KEY="your-daytona-key"
harbor serve

Choose a client

Once the server is running, there are four ways to interact with it:

HTTP / cURL
Harbor CLI with --server
Python SDK (Harbor / AsyncHarbor)
MCP

Choose one of the examples below to submit a job:

HTTP / cURL
Harbor CLI
Python SDK
MCP

Open Submit job, select Local server, leave the Bearer field empty, and click Send on the prefilled example. Or run:

curl http://127.0.0.1:8390/jobs/submit \
  -H 'Content-Type: application/json' \
  -d '{
    "job": {
      "tasks": [{"name": "hello-world/hello-world"}],
      "agents": [{"name": "oracle"}],
      "environment": {"type": "docker"}
    }
  }'

The playground sends real requests from your browser. Allow local-network access if prompted. If blocked, use cURL or http://127.0.0.1:8390/docs.

The CLI submits a job config to POST /jobs/submit. --watch follows progress:

harbor run --server http://127.0.0.1:8390 \
  --task hello-world/hello-world \
  --agent oracle --env docker --watch

To submit an existing config, use harbor run --server http://127.0.0.1:8390 --config job.json --watch.

Harbor() defaults to http://127.0.0.1:8390 and reads HARBOR_API_KEY if set. Run this with python submit_job.py:

submit_job.py

from harbor import Harbor

client = Harbor()
job = client.submit_job(job={
    "tasks": [{"name": "hello-world/hello-world"}],
    "agents": [{"name": "oracle"}],
    "environment": {"type": "docker"},
})
job_id = job.job_id
print(job_id)
print(client.get_job(job_id))
print(client.list_rollouts(job_id=job_id))
client.close()

job accepts a dictionary or JobConfig; responses are typed models. Set base_url to connect remotely. AsyncHarbor provides the same methods with await.Select Python on any endpoint page for its SDK example.

Harbor exposes MCP at http://127.0.0.1:8390/mcp. No authentication is needed for this local example.

Configure MCP permanently

claude mcp add --transport http --scope user harbor http://127.0.0.1:8390/mcp

codex mcp add harbor --url http://127.0.0.1:8390/mcp

{
  "mcpServers": {
    "harbor": {
      "url": "http://127.0.0.1:8390/mcp"
    }
  }
}

For Cursor, add the entry to ~/.cursor/mcp.json. Other clients can use the same URL with Streamable HTTP.

Per conversation: an agent with HTTP tools can communicate with MCP directly using the prompt below. Otherwise, configure MCP above first.

Use the Harbor MCP server at http://127.0.0.1:8390/mcp to run hello-world/hello-world with oracle on Docker. Show the job ID, job, and rollouts.

The server downloads the task from Hub and returns job_id. For local tasks, use path instead of name; paths refer to the server’s filesystem.

Run Codex with an OpenAI API key

Keep the server running. Supply your OpenAI key per job:

HTTP / cURL
Harbor CLI
Python SDK
MCP

curl http://127.0.0.1:8390/jobs/submit \
  -H 'Content-Type: application/json' \
  -d '{
    "job": {
      "tasks": [{"name": "hello-world/hello-world"}],
      "agents": [{
        "name": "codex",
        "model_name": "openai/gpt-6.1-sol",
        "env": {"OPENAI_API_KEY": "your-openai-key"}
      }],
      "environment": {"type": "docker"}
    }
  }'

harbor run --server http://127.0.0.1:8390 \
  --task hello-world/hello-world \
  --agent codex --model openai/gpt-6.1-sol \
  --agent-env OPENAI_API_KEY=your-openai-key \
  --env docker --watch

submit_job.py

from harbor import Harbor

client = Harbor()
job = client.submit_job(job={
    "tasks": [{"name": "hello-world/hello-world"}],
    "agents": [{
        "name": "codex",
        "model_name": "openai/gpt-6.1-sol",
        "env": {"OPENAI_API_KEY": "your-openai-key"},
    }],
    "environment": {"type": "docker"},
})
job_id = job.job_id
print(job_id)
print(client.get_job(job_id))
print(client.list_rollouts(job_id=job_id))
client.close()

Replace your-openai-key with your key. This makes real OpenAI API calls; no server restart is needed.

Run Codex on Daytona with an OpenAI API key

Restart the server with Daytona credentials:

uv pip install "harbor[daytona]"
export DAYTONA_API_KEY="your-daytona-key"
harbor serve

Submit the OpenAI key per job using your chosen client:

HTTP / cURL
Harbor CLI
Python SDK
MCP

curl http://127.0.0.1:8390/jobs/submit \
  -H 'Content-Type: application/json' \
  -d '{
    "job": {
      "tasks": [{"name": "hello-world/hello-world"}],
      "agents": [{
        "name": "codex",
        "model_name": "openai/gpt-6.1-sol",
        "env": {"OPENAI_API_KEY": "your-openai-key"}
      }],
      "environment": {"type": "daytona"}
    }
  }'

harbor run --server http://127.0.0.1:8390 \
  --task hello-world/hello-world \
  --agent codex --model openai/gpt-6.1-sol \
  --agent-env OPENAI_API_KEY=your-openai-key \
  --env daytona --watch

submit_job.py

from harbor import Harbor

client = Harbor()
job = client.submit_job(job={
    "tasks": [{"name": "hello-world/hello-world"}],
    "agents": [{
        "name": "codex",
        "model_name": "openai/gpt-6.1-sol",
        "env": {"OPENAI_API_KEY": "your-openai-key"},
    }],
    "environment": {"type": "daytona"},
})
job_id = job.job_id
print(job_id)
print(client.get_job(job_id))
print(client.list_rollouts(job_id=job_id))
client.close()

Check progress and results

Recommended: use the Harbor viewer to monitor live progress and browse results and artifacts:

harbor view --server http://127.0.0.1:8390

Rollouts move from queued to running to finished. Queued rollouts can pause or cancel; running rollouts can cancel through cancelling. Retry creates a new rollout. — Rollout lifecycle.

Check through the API

Use the returned ID with Get job and List rollouts:

JOB_ID="paste-job-id"
curl "http://127.0.0.1:8390/jobs/$JOB_ID"
curl "http://127.0.0.1:8390/rollouts?job_id=$JOB_ID"

Poll until finished or cancelled. finished means execution ended; inspect rollout error_type and rewards for the outcome.Get rollout returns its full result and artifact URI map. Pass a file URI to Download, or use client.download(uri, destination) to save it locally.

Request behavior

Submit a JobConfig; optional /jobs/resolve returns a lock for inspection, not submission.
Lists return summaries and next_cursor; pass it as cursor with unchanged filters for the next page. Detail endpoints return full records.
Pause affects queued rollouts. Cancel stops queued and running rollouts; soft: true lets running rollouts finish. Retry creates a new rollout ID in the same job.
Submission and retry accept Idempotency-Key (idempotency_key in the SDK). Reuse it after a lost response; duplicates return 409 with the original ID. The SDK does not retry requests automatically.
HTTP errors return {"error": {"code": "...", "message": "..."}}; the SDK raises harbor.client.APIError. Harbor-API-Version is optional; the SDK supplies it.

Server settings

Setting	Behavior
`--host`, `--port`	Default: `127.0.0.1:8390`.
`--data-dir`	Defaults to `.harbor`; persists jobs, results, and artifacts. Use one server process per directory.
`--max-concurrent`	Default: `8092` running rollouts across all jobs. Each job also has `n_concurrent_trials`.
`HARBOR_API_KEY`	Optional locally; required for non-local binding or relay. When set, clients send `Authorization: Bearer <key>`. The CLI and SDK read it from their environment.

Use HTTPS for remote deployments. Set sandbox-provider credentials, such as DAYTONA_API_KEY, on the server; send model credentials per job through agents[].env. environment.env sets variables inside the sandbox, not provider credentials. The API & SDK tab has the endpoint reference, and your server exposes its OpenAPI schema at /openapi.json.

Getting started

Core concepts

Tasks

Datasets

Jobs

Harbor serve

Agents

Sandboxes

Plugins

Results

Harbor Hub

Hosted Harbor

Rewardkit

Tutorials

Open Source Policy

Telemetry

Start the server

Choose a client

Check progress and results

Server settings

​Start the server

​Choose a client

​Check progress and results

​Server settings

Start the server

Choose a client

Check progress and results

Server settings