API server

Start a Harbor server and connect through HTTP, the CLI, the Python SDK, or MCP.

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:

1. HTTP / cURL
2. Harbor CLI with --server
3. Python SDK (Harbor / AsyncHarbor)
4. MCP

Choose one of the examples below to submit a job:

HTTP / cURL

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.

Harbor CLI

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.

Python SDK

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.

MCP

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

Configure MCP permanently

Claude Code

claude mcp add --transport http --scope user harbor 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

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 CLI

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

Python SDK

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()

MCP

Use the Harbor MCP server at http://127.0.0.1:8390/mcp to run hello-world/hello-world with Codex (openai/gpt-6.1-sol) on Docker, setting OPENAI_API_KEY=your-openai-key in the agent env. Show the job ID, job, and rollouts.

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

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 CLI

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

Python SDK

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()

MCP

Use the Harbor MCP server at http://127.0.0.1:8390/mcp to run hello-world/hello-world with Codex (openai/gpt-6.1-sol) on Daytona, setting OPENAI_API_KEY=your-openai-key in the agent env. Show the job ID, job, and rollouts.

​

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

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.