Harbor

Runta’s Harbor integration is a Harbor environment provider backed by the Runta Python SDK. Harbor still owns the job, task, agent, verifier, and artifact flow; Runta provides the isolated runtime where each trial runs. Treat the provider package as pre-release unless your workspace release channel says otherwise.

The provider import path is:

runta_harbor.environment:RuntaEnvironment

Install

Install the Runta SDK with the Harbor extra from the provider package source or your workspace release channel in a Python 3.12, 3.13, or 3.14 environment. The examples below use Python 3.12; replace 3.12 with your chosen supported version if needed.

pip

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "runta-sdk[harbor]"

uv

uv venv --python 3.12
source .venv/bin/activate
uv pip install "runta-sdk[harbor]"

This installs the Runta SDK, the runta_harbor provider module, Harbor, and the harbor CLI into the same Python environment.

Set your Runta credentials:

export RUNTA_TOKEN=rt_...

The SDK defaults to the hosted Runta API at https://api.runta.dev. Set RUNTA_ENDPOINT only when targeting a local, staging, or self-hosted API.

Create a Demo Task

If you do not already have a Harbor task, create this minimal task in your current directory:

mkdir -p square-2/environment square-2/solution square-2/tests

cat > square-2/task.toml <<'EOF'
schema_version = "1.1"

[task]
name = "demo/square-2"
description = "Small Runta Harbor demo task."
authors = []
keywords = ["runta", "harbor", "demo"]

[verifier]
timeout_sec = 30.0

[agent]
timeout_sec = 30.0

[environment]
cpus = 1
memory_mb = 1024
storage_mb = 1024
gpus = 0
EOF

cat > square-2/instruction.md <<'EOF'
Write the square of 2 to /tmp/answer.txt.
EOF

cat > square-2/environment/Dockerfile <<'EOF'
FROM alpine:3.20
EOF

cat > square-2/solution/solve.sh <<'EOF'
#!/bin/sh
set -eu
echo 4 > /tmp/answer.txt
EOF

cat > square-2/tests/test.sh <<'EOF'
#!/bin/sh
set -eu
mkdir -p /logs/verifier
if [ "$(cat /tmp/answer.txt 2>/dev/null || true)" = "4" ]; then
  echo 1 > /logs/verifier/reward.txt
else
  echo 0 > /logs/verifier/reward.txt
fi
EOF

chmod +x square-2/solution/solve.sh square-2/tests/test.sh

Then run it:

harbor

harbor run \
  -p square-2 \
  -a oracle \
  --environment-import-path runta_harbor.environment:RuntaEnvironment \
  --ek mode=auto

uv

uvx --with "runta-sdk[harbor]" harbor run \
  -p square-2 \
  -a oracle \
  --environment-import-path runta_harbor.environment:RuntaEnvironment \
  --ek mode=auto

The demo runs Harbor’s built-in oracle agent against a simple square-number task and prints the trial result when Harbor finishes.

Use in a Harbor Job

Create a Harbor JobConfig with EnvironmentConfig(import_path=...).

from harbor.job import Job
from harbor.models.job.config import JobConfig
from harbor.models.trial.config import AgentConfig, EnvironmentConfig, TaskConfig

RUNTA_ENV_IMPORT_PATH = "runta_harbor.environment:RuntaEnvironment"

config = JobConfig(
    job_name="runta-harbor-demo",
    jobs_dir="jobs",
    n_concurrent_trials=2,
    agents=[AgentConfig(name="oracle")],
    environment=EnvironmentConfig(
        import_path=RUNTA_ENV_IMPORT_PATH,
        type=None,
        kwargs={
            "mode": "auto",
        },
    ),
    tasks=[
        TaskConfig(path="square-2"),
    ],
)

job = await Job.create(config)
result = await job.run()

Use RUNTA_TOKEN or RUNTA_CONFIG for credentials. Use environment kwargs such as endpoint only when overriding the default API endpoint.

What Runta Handles

RuntaEnvironment implements Harbor’s normal environment interface:

• start creates and starts a Runta runtime.
• exec runs Harbor agent and verifier commands in that runtime.
• upload_file and upload_dir copy solutions, tests, and task assets in.
• download_file and download_dir copy verifier logs and reward artifacts out.
• Compose sidecar service_exec, sidecar file and directory downloads, and stop_service.
• set_network_policy maps Harbor network policies onto Runta egress controls.
• stop deletes the runtime after the trial by default.

Normal Harbor tasks can use Runta for agent execution, verifier execution, task asset upload, solution upload, healthchecks, main-service logs, main-service artifacts, compose sidecar artifact collection, and direct file or directory copy operations.

The provider selects direct, docker, or compose mode automatically. Set --ek mode=direct, --ek mode=docker, or --ek mode=compose to force a mode.

Current Limitations

• harbor run -e runta is not available until Harbor registers Runta as an upstream environment type. Use --environment-import-path runta_harbor.environment:RuntaEnvironment for now.
• Compose mode relies on Docker-in-Runta support for privileged Compose fields such as cap_add, privileged, and devices; unsupported host privileges fail at Docker Compose runtime.
• GPU, TPU, Windows, and mounted-resource task requirements are not supported.
• CPU and memory requests are supported, but hard limits are not currently enforced. Storage override settings are accepted by Harbor but not applied to Runta runtime creation yet.
• Private registry pulls depend on Docker credentials already being available inside the Runta runtime; there is no Harbor-specific registry login flow yet.

Troubleshooting

If Harbor fails with No module named 'runta_harbor', the harbor command is running from a Python environment that does not have runta-sdk[harbor] installed. This commonly happens when which harbor points to a global uv tool install, such as ~/.local/bin/harbor.

Use uvx for quick fix:

uvx --with "runta-sdk[harbor]" harbor run \
  -p square-2 \
  -a oracle \
  --environment-import-path runta_harbor.environment:RuntaEnvironment \
  --ek mode=auto