### Install and Run Harbour without Docker

Source: https://github.com/geekforbrains/harbour/blob/main/README.md

Instructions for setting up and running Harbour directly using Node.js. This involves cloning the repository, installing dependencies, building the project, and starting the server. The application will be accessible at http://localhost:3000.

```bash
git clone https://github.com/geekforbrains/harbour.git
cd harbour
npm install
npm run build
npm start
```

--------------------------------

### Harbour API Authentication Examples

Source: https://context7.com/geekforbrains/harbour/llms.txt

Examples of how to authenticate with the Harbour API using agent and admin keys, and how to log in to the dashboard.

```bash
# Agent API key (issued when an agent is created)
curl -H "Authorization: Bearer hbr_<agent_key>" \
  https://harbour.example.com/api/agents/<id>/next
```

```bash
# Admin API key (full management access, resolves to creating user's identity)
curl -H "Authorization: Bearer hbr_adm_<admin_key>" \
  https://harbour.example.com/api/agents
```

```bash
# Login (dashboard session)
curl -X POST https://harbour.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret"}'
# Response sets harbour_session cookie (httpOnly, 30-day expiry)
```

```bash
# Rotate an agent's API key
curl -X POST https://harbour.example.com/api/agents/<id>/rotate-key \
  -H "Authorization: Bearer hbr_adm_<admin_key>"
# Returns: { "apiKey": "hbr_..." } — new key, shown once
```

--------------------------------

### Start Dev Server in Worktree

Source: https://github.com/geekforbrains/harbour/blob/main/CLAUDE.md

Starts a development server in a worktree. Pick an available port from the 3010-3020 range. Ensure you check for existing port usage before starting.

```bash
# Start dev server in a worktree (pick an available port from 3010-3020)
npm run dev -- -p 3010
```

--------------------------------

### Gemini CLI Provider Command Example

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

Example of command-line arguments for the Gemini CLI provider, including prompt, output format, and session resumption.

```bash
--prompt "..." --yolo -o stream-json --resume
```

--------------------------------

### Clone and Run Harbour with Docker

Source: https://github.com/geekforbrains/harbour/blob/main/README.md

Use these commands to clone the Harbour repository and start the application using Docker. Ensure Docker is installed. The application will be accessible at http://localhost:3030.

```bash
git clone https://github.com/geekforbrains/harbour.git
cd harbour
make run
```

--------------------------------

### Get All Settings

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieves all current system settings.

```APIDOC
## GET /api/settings

### Description
Retrieves all current system settings.

### Method
GET

### Endpoint
/api/settings
```

--------------------------------

### launchd Plist Configuration Example

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

This is an example of a launchd plist file used for integrating the Harbour agent runner with macOS's launchd service, ensuring it runs periodically.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.harbour.agent-runner</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/harbour</string>
    <string>agent</string>
    <string>run</string>
  </array>
  <key>StartInterval</key>
  <integer>60</integer>
  <key>StandardOutPath</key>
  <string>/Users/user/.harbour/runner.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/user/.harbour/runner.err.log</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>HOME</key>
    <string>/Users/user</string>
  </dict>
</dict>
</plist>
```

--------------------------------

### Get All Settings

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieve the current system-wide settings.

```http
GET /api/settings
```

--------------------------------

### Codex Provider Command Example

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

Example of command-line arguments for the Codex provider, emphasizing JSON output, security bypass, and reasoning effort levels.

```bash
exec --dangerously-bypass-approvals-and-sandbox --json --resume
```

--------------------------------

### Start Harbour with Remote Profile using Docker

Source: https://github.com/geekforbrains/harbour/blob/main/README.md

This command starts Harbour with the 'remote' profile, which includes an additional container for simulating a remote runner setup. This is useful for testing the connection flow locally.

```bash
docker compose --profile remote up -d
```

--------------------------------

### Schedule Examples

Source: https://github.com/geekforbrains/harbour/blob/main/GUIDE.md

Examples of different schedule configurations, including intervals and weekly timings. The API also accepts human-readable strings and cron expressions which are normalized to JSON.

```json
{"every": 5}
```

```json
{"every": 60}
```

```json
{"every": 1440}
```

```json
{"days": [1, 2, 3, 4, 5], "time": "09:00"}
```

```json
{"days": [0, 1, 2, 3, 4, 5, 6], "time": "14:30"}
```

```json
{"days": [5], "time": "09:00"}
```

```json
every 5 minutes
```

```json
daily at 9am
```

```json
weekly on friday at 9am
```

```cron
*/5 * * * *
```

```cron
0 9 * * 1-5
```

--------------------------------

### Claude Code Provider Command Example

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

Example of command-line arguments for the Claude Code provider, including output format, verbosity, and session management flags.

```bash
--output-format stream-json --verbose --dangerously-skip-permissions --session-id "new" --resume
```

--------------------------------

### Workflow Only: One-Liner Example

Source: https://github.com/geekforbrains/harbour/blob/main/WORKFLOW.md

A concise example of a workflow-only job that fetches and processes metrics using `curl` and `jq`. No separate script file is needed as the command itself constitutes the workflow.

```bash
# workflow_command: curl -s https://api.example.com/metrics | jq '.summary'
# workflow_only: true
# (no files needed — the command itself is the workflow)
```

--------------------------------

### Install the launchd service for automatic polling (macOS)

Source: https://context7.com/geekforbrains/harbour/llms.txt

Installs the launchd service for automatic polling every 60 seconds on macOS.

```APIDOC
## npm run harbour -- agent install

### Description
Installs the launchd service for automatic polling every 60 seconds (macOS).

### Command
npm run harbour -- agent install

### Notes
Creates `~/Library/LaunchAgents/com.harbour.agent-runner.plist`.
Logs to `~/.harbour/runner.log`.
```

--------------------------------

### Run Harbour without Docker

Source: https://context7.com/geekforbrains/harbour/llms.txt

Commands to install dependencies, build, and start the Harbour application locally without using Docker.

```bash
npm install && npm run build && npm start  # http://localhost:3000
```

--------------------------------

### Get All System Settings

Source: https://context7.com/geekforbrains/harbour/llms.txt

Use this command to retrieve all current system settings for Harbour. Requires an admin key for authorization.

```bash
curl -H "Authorization: Bearer hbr_adm_<admin_key>" \
  https://harbour.example.com/api/settings
```

--------------------------------

### Install Harbour Agent Runner

Source: https://github.com/geekforbrains/harbour/blob/main/README.md

Installs the local Harbour agent runner. The runner polls for work, spawns CLI tools, streams output, and posts results. It polls every 60 seconds.

```bash
npm run harbour -- agent install
```

--------------------------------

### Get All System Settings

Source: https://context7.com/geekforbrains/harbour/llms.txt

Retrieves all current system settings for the Harbour instance. This includes configuration like timezone and signup status.

```APIDOC
## GET /api/settings

### Description
Retrieves all current system settings for the Harbour instance.

### Method
GET

### Endpoint
https://harbour.example.com/api/settings

### Request Headers
- **Authorization**: Bearer hbr_adm_<admin_key>

### Response
#### Success Response (200)
- **timezone** (string) - The current system timezone.
- **signup_enabled** (string) - Indicates if user signups are enabled ('true' or 'false').
- ... (other settings)

### Response Example
```json
{
  "timezone": "America/New_York",
  "signup_enabled": "true"
}
```
```

--------------------------------

### Create a Database

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Creates a new database with a specified name and columns. Each table automatically gets an `_id` column.

```APIDOC
## POST /api/databases

### Description
Creates a new database with a given name and a list of column definitions. Each database table automatically includes an auto-incrementing `_id` column.

### Method
POST

### Endpoint
/api/databases

### Parameters
#### Request Body
- **name** (string) - Required - The name of the database.
- **columns** (array) - Required - An array of column objects, where each object has:
  - **name** (string) - Required - The name of the column.
  - **type** (string) - Required - The data type of the column (e.g., `TEXT`, `INTEGER`, `REAL`).
  - **required** (boolean) - Optional - Specifies if the column is required.
```

--------------------------------

### Update Harbour Installation

Source: https://github.com/geekforbrains/harbour/blob/main/terraform/README.md

To update Harbour, SSH into the droplet, navigate to the Harbour directory, pull the latest changes, install dependencies, build the project, and restart the Harbour and agent runner services.

```bash
ssh root@<droplet-ip>
cd /opt/harbour
git pull
npm ci
npm run build
systemctl restart harbour
systemctl restart harbour-agent-runner
```

--------------------------------

### Documentation Access

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

Endpoints to retrieve API guides.

```APIDOC
## GET /api/guide

### Description
Retrieves the Agent API guide, documented in GUIDE.md.

### Method
GET

### Endpoint
/api/guide

### Auth
none
```

```APIDOC
## GET /api/admin-guide

### Description
Retrieves the Admin API guide, documented in ADMIN_GUIDE.md.

### Method
GET

### Endpoint
/api/admin-guide

### Auth
withUserAuth
```

--------------------------------

### Monitor Cloud-Init Bootstrap Process

Source: https://github.com/geekforbrains/harbour/blob/main/terraform/README.md

After applying Terraform, monitor the cloud-init process on the newly created droplet to ensure Harbour is successfully installed and configured. Look for the 'HARBOUR READY' message in the output.

```bash
ssh root@<droplet-ip> 'tail -f /var/log/cloud-init-output.log'
```

--------------------------------

### Create a Weekly Agent Job

Source: https://context7.com/geekforbrains/harbour/llms.txt

Schedule a new agent job to run weekly on specific days and times. This example sets the job to run on weekdays at 9:00 AM.

```bash
# Create a weekly agent job (weekdays at 9am)
curl -X POST https://harbour.example.com/api/agents/<agent_id>/jobs \
  -H "Authorization: Bearer hbr_adm_<admin_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Newsletter",
    "instructions": "Write and send the weekly newsletter to subscribers.",
    "schedule": {"days":[1,2,3,4,5],"time":"09:00"}
  }'
```

--------------------------------

### Runner Configuration Example

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

This JSON structure defines the configuration for Harbour runners, specifying agent details, API keys, CLI tools, model preferences, and server URLs.

```json
{
  "runners": [
    {
      "agentId": "uuid",
      "name": "Agent Name",
      "apiKey": "hbr_...",
      "cli": "claude|codex|gemini",
      "model": "sonnet|null",
      "thinking": "high|null",
      "url": "https://harbour.example.com"
    }
  ]
}
```

--------------------------------

### Playwright CLI Utility Commands

Source: https://github.com/geekforbrains/harbour/blob/main/CLAUDE.md

Provides examples of other useful playwright-cli commands, including capturing the accessibility tree, interacting with elements, and evaluating JavaScript.

```bash
playwright-cli snapshot           # accessibility tree (element refs)
playwright-cli click <ref>        # interact with elements
playwright-cli eval "js expression"  # run JS in page context
```

--------------------------------

### Create a Database

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Create a new database with a specified name and columns. Each table automatically includes an `_id` column.

```http
POST /api/databases
Content-Type: application/json

{
  "name": "metrics",
  "columns": [
    { "name": "date", "type": "TEXT", "required": true },
    { "name": "value", "type": "REAL" }
  ]
}
```

--------------------------------

### List and Create Projects

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieve a list of all projects or create a new project with a given name.

```http
GET  /api/projects
```

```http
POST /api/projects    { "name": "Marketing" }
```

--------------------------------

### Create a Project

Source: https://context7.com/geekforbrains/harbour/llms.txt

Create a new project to group entities. Projects are view-layer groupings and do not own entities.

```bash
curl -X POST https://harbour.example.com/api/projects \
  -H "Authorization: Bearer hbr_adm_<admin_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Marketing Q2"}'
```

--------------------------------

### Workflow-Only Job Example

Source: https://github.com/geekforbrains/harbour/blob/main/README.md

Example of a workflow-only job that checks an API. The command receives the run payload on stdin and prints the result to stdout. This mode is useful for standalone scheduled commands.

```bash
# Example: workflow-only job that checks an API
# workflow_command: python3 check_health.py
# Receives run payload on stdin, prints result to stdout
```

--------------------------------

### Run Harbour with Docker

Source: https://context7.com/geekforbrains/harbour/llms.txt

Commands to build, run, and manage the Harbour Docker container. Recommended for production environments.

```bash
git clone https://github.com/geekforbrains/harbour.git && cd harbour
make run        # starts on http://localhost:3030, state in ./data
make logs       # follow container logs
make down       # stop
make rebuild    # rebuild image and restart
```

--------------------------------

### Create a Documentation Entry

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Create a new documentation entry with a title and content. Content supports Markdown.

```http
POST /api/docs
Content-Type: application/json

{ "title": "Brand Guidelines", "content": "## Voice\n..." }
```

--------------------------------

### Create a One-Off Agent Run

Source: https://context7.com/geekforbrains/harbour/llms.txt

Creates and initiates an immediate task for an agent, outside of any scheduled job. Supports specifying agent ID, name, instructions, and attaching specific documents and environment variables. Requires an admin key for authorization.

```bash
curl -X POST https://harbour.example.com/api/runs \
  -H "Authorization: Bearer hbr_adm_<admin_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "uuid",
    "name": "Analyze Q1 metrics",
    "instructions": "Review the attached report and summarize key findings.",
    "docIds": ["uuid1"],
    "envVarIds": ["uuid2"]
  }'
```

--------------------------------

### Get Run Activity

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieves the activity log for a specific run.

```APIDOC
## Get Run Activity

### Description
Retrieves the activity log for a specific run.

### Method
GET

### Endpoint
/api/runs/:id/activity

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the run.
```

--------------------------------

### Create a Document

Source: https://context7.com/geekforbrains/harbour/llms.txt

Create a new versioned markdown document. The response includes the document's ID and title.

```bash
# Create a doc
curl -X POST https://harbour.example.com/api/docs \
  -H "Authorization: Bearer hbr_<key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Brand Voice","content":"## Tone\nFriendly, concise, technically precise..."}'
```

--------------------------------

### Get or Delete a Database

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieve or delete a specific database using its ID.

```http
GET    /api/databases/:id
```

```http
DELETE /api/databases/:id
```

--------------------------------

### Create a project

Source: https://context7.com/geekforbrains/harbour/llms.txt

Creates a new project to organize entities. Projects act as view-layer groupings.

```APIDOC
## POST /api/projects

### Description
Creates a project.

### Method
POST

### Endpoint
https://harbour.example.com/api/projects

### Headers
- Authorization: Bearer hbr_adm_<admin_key>
- Content-Type: application/json

### Request Body
- **name** (string) - Required - The name of the project.

### Request Example
{
  "name":"Marketing Q2"
}
```

--------------------------------

### Get Run Activity API

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieve the activity log for a specific run.

```http
GET /api/runs/:id/activity
```

--------------------------------

### Get / Delete a Database

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Provides endpoints for retrieving and deleting a specific database by its ID.

```APIDOC
## GET /api/databases/:id

### Description
Retrieves a specific database by its ID.

### Method
GET

### Endpoint
/api/databases/:id

## DELETE /api/databases/:id

### Description
Deletes a specific database by its ID.

### Method
DELETE

### Endpoint
/api/databases/:id
```

--------------------------------

### Get a Run

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieves details of a specific run, including its complete activity log.

```APIDOC
## Get a Run

### Description
Retrieves details of a specific run, including its complete activity log.

### Method
GET

### Endpoint
/api/runs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the run.
```

--------------------------------

### Create a Doc

Source: https://github.com/geekforbrains/harbour/blob/main/GUIDE.md

Use this endpoint to create a new top-level document. Documents are linked to jobs and automatically included in the `/next` payload.

```http
POST /api/docs
Content-Type: application/json

{ "title": "Content Calendar", "content": "## March 2024\n..." }
```

--------------------------------

### Get / Update / Delete a Job

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Performs operations on a specific job identified by its ID.

```APIDOC
## Get / Update / Delete a Job

### Description
Performs operations on a specific job identified by its ID.

### Method
GET, PUT, DELETE

### Endpoint
/api/jobs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the job.

### Request Body (for PUT)
- **name** (string) - Optional - The new name for the job.
- **instructions** (string) - Optional - The new instructions for the job.
- **schedule** (object) - Optional - The updated schedule for the job.
- **archived** (boolean) - Optional - Whether the job is archived.
```

--------------------------------

### Get / Update / Delete an Agent

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Performs operations on a specific agent identified by its ID.

```APIDOC
## Get / Update / Delete an Agent

### Description
Performs operations on a specific agent identified by its ID.

### Method
GET, PUT, DELETE

### Endpoint
/api/agents/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent.

### Request Body (for PUT)
- **name** (string) - Optional - The new name for the agent.
- **description** (string) - Optional - The new description for the agent.
```

--------------------------------

### Get, Update, or Delete a Document

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Perform operations on a specific documentation entry using its ID.

```http
GET    /api/docs/:id
```

```http
PUT    /api/docs/:id    { "title": "...", "content": "..." }
```

```http
DELETE /api/docs/:id
```

--------------------------------

### Get a Run API

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieve a specific run by its ID, including its complete activity log.

```http
GET /api/runs/:id
```

--------------------------------

### List / Create Projects

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Provides endpoints for listing all projects and creating new projects.

```APIDOC
## GET /api/projects

### Description
Retrieves a list of all available projects.

### Method
GET

### Endpoint
/api/projects

## POST /api/projects

### Description
Creates a new project.

### Method
POST

### Endpoint
/api/projects

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new project.
```

--------------------------------

### Get / Update / Delete a Doc

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Provides endpoints for retrieving, updating, and deleting a specific document by its ID.

```APIDOC
## GET /api/docs/:id

### Description
Retrieves a specific document by its ID.

### Method
GET

### Endpoint
/api/docs/:id

## PUT /api/docs/:id

### Description
Updates an existing document identified by its ID. Both title and content can be modified.

### Method
PUT

### Endpoint
/api/docs/:id

### Parameters
#### Request Body
- **title** (string) - Optional - The new title for the document.
- **content** (string) - Optional - The new content for the document.

## DELETE /api/docs/:id

### Description
Deletes a specific document by its ID.

### Method
DELETE

### Endpoint
/api/docs/:id
```

--------------------------------

### Get, Update, or Delete an Environment Variable

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Perform operations on a specific environment variable using its ID.

```http
GET    /api/env-vars/:id
```

```http
PUT    /api/env-vars/:id    { "name": "...", "value": "..." }
```

```http
DELETE /api/env-vars/:id
```

--------------------------------

### Get / Update / Delete a Job API

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Endpoints for retrieving, updating, or deleting a specific job by its ID.

```http
GET    /api/jobs/:id
PUT    /api/jobs/:id    { "name": "...", "instructions": "...", "schedule": {...}, "archived": false }
DELETE /api/jobs/:id
```

--------------------------------

### Create a Database

Source: https://context7.com/geekforbrains/harbour/llms.txt

Creates a new SQLite database for agent use. If a database with the same name already exists, the existing one is returned (idempotent). Requires a bearer token for authorization and specifies column definitions.

```bash
curl -X POST https://harbour.example.com/api/databases \
  -H "Authorization: Bearer hbr_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tweet_history",
    "columns": [
      {"name":"date","type":"TEXT","required":true},
      {"name":"text","type":"TEXT","required":true},
      {"name":"likes","type":"INTEGER"},
      {"name":"impressions","type":"INTEGER"}
    ]
  }'
```

--------------------------------

### Get / Update / Delete an Agent API

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Endpoints for retrieving, updating, or deleting a specific agent by its ID.

```http
GET    /api/agents/:id
PUT    /api/agents/:id    { "name": "New Name", "description": "..." }
DELETE /api/agents/:id
```

--------------------------------

### Initialize and Plan Terraform Deployment

Source: https://github.com/geekforbrains/harbour/blob/main/terraform/README.md

Before applying, initialize Terraform and review the deployment plan. Ensure your terraform.tfvars file is correctly configured with your DigitalOcean token, domain, email, and SSH key names.

```bash
cd terraform/
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars — fill in do_token, domain, letsencrypt_email,
basic_auth_password (use: openssl rand -base64 24), and ssh_key_names.

terraform init
terraform plan
```

--------------------------------

### Get and Delete Runs

Source: https://context7.com/geekforbrains/harbour/llms.txt

Retrieve a single run with its activity log and attachments, or delete a run and its associated attachments.

```bash
curl -H "Authorization: Bearer hbr_adm_<admin_key>" \
  https://harbour.example.com/api/runs/<run_id>
```

```bash
curl -X DELETE https://harbour.example.com/api/runs/<run_id> \
  -H "Authorization: Bearer hbr_adm_<admin_key>"
```

--------------------------------

### Set up a new agent with a recurring job

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

This sequence of API calls is used to set up a new agent and associate it with a recurring job, including its documentation and environment variables.

```APIDOC
## POST /api/agents

### Description
Creates a new agent and saves its API key.

### Method
POST

### Endpoint
/api/agents

## POST /api/agents/:id/jobs

### Description
Creates a new job associated with an agent, including its schedule and instructions.

### Method
POST

### Endpoint
/api/agents/:id/jobs

## POST /api/docs

### Description
Creates documentation that can be used by an agent.

### Method
POST

### Endpoint
/api/docs

## POST /api/jobs/:id/docs

### Description
Links existing documentation to a specific job.

### Method
POST

### Endpoint
/api/jobs/:id/docs

## POST /api/env-vars

### Description
Creates environment variables, such as API keys or tokens.

### Method
POST

### Endpoint
/api/env-vars

## POST /api/jobs/:id/env-vars

### Description
Links environment variables to a specific job.

### Method
POST

### Endpoint
/api/jobs/:id/env-vars
```

--------------------------------

### List Configured CLI Runners

Source: https://context7.com/geekforbrains/harbour/llms.txt

List all configured Harbour agents by reading the ~/.harbour/runners.json file.

```bash
npm run harbour -- agent list
```

--------------------------------

### Get / Update / Delete an Env Var

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Provides endpoints for retrieving, updating, and deleting a specific environment variable by its ID.

```APIDOC
## GET /api/env-vars/:id

### Description
Retrieves a specific environment variable by its ID.

### Method
GET

### Endpoint
/api/env-vars/:id

## PUT /api/env-vars/:id

### Description
Updates an existing environment variable identified by its ID. Both name and value can be modified.

### Method
PUT

### Endpoint
/api/env-vars/:id

### Parameters
#### Request Body
- **name** (string) - Optional - The new name for the environment variable.
- **value** (string) - Optional - The new value for the environment variable.

## DELETE /api/env-vars/:id

### Description
Deletes a specific environment variable by its ID.

### Method
DELETE

### Endpoint
/api/env-vars/:id
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/geekforbrains/harbour/blob/main/CLAUDE.md

Commands for the development workflow: linting, running unit tests, and building the production application. These should be run after making changes.

```bash
# 1. Make changes, then validate
npm run lint                    # ESLint (pre-existing `any` warnings are expected)
npm run test                    # Vitest unit tests
npm run build                   # Next.js production build
```

--------------------------------

### Get, Update, or Delete a Project

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Perform operations on a specific project using its ID. Deleting a project only removes the grouping.

```http
GET    /api/projects/:id
```

```http
PUT    /api/projects/:id    { "name": "New Name" }
```

```http
DELETE /api/projects/:id
```

--------------------------------

### Create a Harbour Agent

Source: https://context7.com/geekforbrains/harbour/llms.txt

Use this endpoint to create a 'harbour' type agent, which uses the built-in CLI runner. The API key is returned once and must be saved.

```bash
# Create a harbour agent (Claude Code, uses local runner)
curl -X POST https://harbour.example.com/api/agents \
  -H "Authorization: Bearer hbr_adm_<admin_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer",
    "description": "Reviews PRs and writes code",
    "type": "harbour",
    "cli": "claude",
    "model": "claude-sonnet-4-5",
    "thinking": "high"
  }'
```

--------------------------------

### Get a single run with its full activity log and attachments

Source: https://context7.com/geekforbrains/harbour/llms.txt

Retrieves a specific run, including its complete activity log and any associated attachments.

```APIDOC
## GET /api/runs/<run_id>

### Description
Retrieves a single run with its full activity log and attachments.

### Method
GET

### Endpoint
https://harbour.example.com/api/runs/<run_id>

### Headers
- Authorization: Bearer hbr_adm_<admin_key>
```

--------------------------------

### Create a database

Source: https://context7.com/geekforbrains/harbour/llms.txt

Creates a new database, which is represented as a SQLite table. If a database with the same name already exists, it will be returned.

```APIDOC
## POST /api/databases

### Description
Creates a new database. Databases are SQLite tables managed by agents. If a database with the specified name already exists, the existing one is returned (idempotent).

### Method
POST

### Endpoint
https://harbour.example.com/api/databases

### Headers
- Authorization: Bearer hbr_<key>
- Content-Type: application/json

### Request Body
- **name** (string) - Required - The name of the database.
- **columns** (array) - Required - An array of column definitions.
  - **name** (string) - Required - The name of the column.
  - **type** (string) - Required - The data type of the column (e.g., 'TEXT', 'INTEGER').
  - **required** (boolean) - Optional - Whether the column is required.

### Request Example
```json
{
  "name": "tweet_history",
  "columns": [
    {"name":"date","type":"TEXT","required":true},
    {"name":"text","type":"TEXT","required":true},
    {"name":"likes","type":"INTEGER"},
    {"name":"impressions","type":"INTEGER"}
  ]
}
```
```

--------------------------------

### Get / Update / Delete a Project

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Provides endpoints for retrieving, updating, and deleting a specific project by its ID. Deleting a project only removes the grouping.

```APIDOC
## GET /api/projects/:id

### Description
Retrieves a specific project by its ID.

### Method
GET

### Endpoint
/api/projects/:id

## PUT /api/projects/:id

### Description
Updates an existing project identified by its ID. The project name can be modified.

### Method
PUT

### Endpoint
/api/projects/:id

### Parameters
#### Request Body
- **name** (string) - Required - The new name for the project.

## DELETE /api/projects/:id

### Description
Deletes a specific project by its ID. Note that this action only removes the project grouping and does not affect any associated entities.

### Method
DELETE

### Endpoint
/api/projects/:id
```

--------------------------------

### List Documentation Entries

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Retrieve a list of all documentation entries, optionally filtered by project ID.

```http
GET /api/docs
```

```http
GET /api/docs?projectId=<id>
```

--------------------------------

### Post Activity (as admin/human)

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Use this to respond to runs in `waiting` status. The run automatically transitions to `pending` when you post a response. `attachment_ids` is optional — upload attachments first, then reference them here.

```APIDOC
## POST /api/runs/:id/activity

### Description
Posts an activity to a run, used for responding to runs in a `waiting` status. The run status automatically transitions to `pending` upon successful posting.

### Method
POST

### Endpoint
/api/runs/:id/activity

### Parameters
#### Request Body
- **content** (string) - Required - The content of the activity response.
- **attachment_ids** (array of strings) - Optional - A list of attachment IDs to associate with the activity.
```

--------------------------------

### Create a Doc

Source: https://github.com/geekforbrains/harbour/blob/main/GUIDE.md

Creates a new top-level document resource.

```APIDOC
## POST /api/docs

### Description
Creates a new document.

### Method
POST

### Endpoint
/api/docs

### Request Body
- **title** (string) - Required - The title of the document.
- **content** (string) - Required - The content of the document.
```

--------------------------------

### Poll for Next Agent Task

Source: https://context7.com/geekforbrains/harbour/llms.txt

An agent polls this endpoint to get the next available task to work on. Returns null or empty if no tasks are pending.

```APIDOC
## GET /api/agents/{agent_id}/next

### Description
An agent polls this endpoint to get the next available task to work on. Returns null or empty if no tasks are pending.

### Method
GET

### Endpoint
https://harbour.example.com/api/agents/$AGENT_ID/next

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

### Request Headers
- **Authorization**: Bearer hbr_<your_api_key>

### Response
#### Success Response (200)
- **run.id** (string) - The ID of the run assigned to the agent.
- **job.name** (string) - The name of the job to be executed.
- (Payload contains all context for the job)

### Response Example
```json
{
  "run": {
    "id": "<run_id>"
  },
  "job": {
    "name": "<job_name>"
  }
}
```
```

--------------------------------

### Environment Stripping for Claude Code

Source: https://github.com/geekforbrains/harbour/blob/main/SPEC.md

This example shows environment variables that are stripped by the runner before spawning a Claude Code process to prevent nested session detection.

```bash
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_SESSION, CLAUDE_CODE_PARENT_SESSION
```

--------------------------------

### Create an Agent API

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Create a new agent. The response includes an apiKey that is shown only once.

```http
POST /api/agents
Content-Type: application/json

{
  "name": "Social Media Bot",
  "description": "Posts content and monitors engagement",
  "type": "external"
}
```

--------------------------------

### Respond to a waiting run

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

These API calls allow you to find runs that are waiting for input, get details about a specific run, and post your response to continue the process.

```APIDOC
## GET /api/runs?filter=waiting

### Description
Finds all runs that are currently in a waiting state and require input.

### Method
GET

### Endpoint
/api/runs

### Query Parameters
- **filter** (string) - Required - Filters the runs to only include those with the status 'waiting'.

## GET /api/runs/:id

### Description
Retrieves detailed information about a specific run, including its activity log.

### Method
GET

### Endpoint
/api/runs/:id

## POST /api/runs/:id/activity

### Description
Posts a response for a specific run, which will automatically transition its status to 'pending'.

### Method
POST

### Endpoint
/api/runs/:id/activity

### Parameters
#### Request Body
- **response** (string) - Required - The response to the run's request for input.
```

--------------------------------

### Create a one-off run

Source: https://context7.com/geekforbrains/harbour/llms.txt

Creates and initiates a one-off run for an agent, allowing for specific instructions, documents, and environment variables.

```APIDOC
## POST /api/runs

### Description
Creates and starts a one-off run for an agent. This allows for immediate task execution outside of scheduled jobs, with the ability to specify associated documents and environment variables.

### Method
POST

### Endpoint
https://harbour.example.com/api/runs

### Headers
- Authorization: Bearer hbr_adm_<admin_key>
- Content-Type: application/json

### Request Body
- **agentId** (string) - Required - The ID of the agent to run the task.
- **name** (string) - Required - A descriptive name for the run.
- **instructions** (string) - Required - The instructions for the agent to follow.
- **docIds** (array of strings) - Optional - IDs of documents to attach to the run.
- **envVarIds** (array of strings) - Optional - IDs of environment variables to attach to the run.

### Request Example
```json
{
  "agentId": "uuid",
  "name": "Analyze Q1 metrics",
  "instructions": "Review the attached report and summarize key findings.",
  "docIds": ["uuid1"],
  "envVarIds": ["uuid2"]
}
```
```

--------------------------------

### Set up a workflow-only job (no agent)

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

This API call is used to create a job that runs a workflow without an associated agent. The script should be placed in `~/.harbour/workflows/` on the runner host.

```APIDOC
## POST /api/jobs

### Description
Creates a job with a `workflowCommand` and schedule. This is used for workflow-only jobs without an agent.

### Method
POST

### Endpoint
/api/jobs

### Parameters
#### Request Body
- **workflowCommand** (string) - Required - The command to execute for the workflow.
- **schedule** (string) - Required - The schedule for the job.
```

--------------------------------

### Create a One-Off Run

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Creates and queues a single run for a specific agent with provided instructions and resources.

```APIDOC
## Create a One-Off Run

### Description
Creates and queues a single run for a specific agent with provided instructions and resources.

### Method
POST

### Endpoint
/api/runs

### Request Body
- **agentId** (string) - Required - The ID of the agent to execute the run.
- **name** (string) - Required - The name of the run.
- **instructions** (string) - Required - The instructions for the agent.
- **docIds** (array of strings) - Optional - IDs of documents to inject into the run.
- **envVarIds** (array of strings) - Optional - IDs of environment variables to inject into the run.
```

--------------------------------

### Configure Harbour Environment Variables

Source: https://context7.com/geekforbrains/harbour/llms.txt

Set environment variables to configure Harbour's behavior, including its home directory, database path, upload limits, and encryption keys.

```bash
# All Harbour state lives under ~/.harbour by default
export HARBOUR_HOME=/data/harbour          # override root directory
export HARBOUR_DB_PATH=/data/harbour.db    # SQLite file path
export HARBOUR_UPLOADS_DIR=/data/uploads   # run attachment storage
export HARBOUR_ENCRYPTION_KEY=<64-char-hex># AES-256-GCM key for env vars
export HARBOUR_MAX_UPLOAD_MB=500           # per-file upload cap (default 500)
```

--------------------------------

### Workflow Only: Health Check Script

Source: https://github.com/geekforbrains/harbour/blob/main/WORKFLOW.md

Example of a bash script for a workflow-only job that checks API health. Ensure the script is placed in `~/.harbour/workflows/` and the `workflow_command` and `workflow_only` settings are configured.

```bash
# workflow_command: bash health_check.sh
# workflow_only: true
```

```bash
#!/bin/bash
# ~/.harbour/workflows/health_check.sh
status=$(curl -s -o /dev/null -w "%{http_code}") https://api.example.com/health
if [ "$status" = "200" ]; then
  echo "API healthy: returned $status"
  exit 0
else
  echo "API unhealthy: returned $status" >&2
  exit 2
fi
```

--------------------------------

### Create an Env Var

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

Creates a new environment variable with a specified name and value.

```APIDOC
## POST /api/env-vars

### Description
Creates a new environment variable with the provided name and value.

### Method
POST

### Endpoint
/api/env-vars

### Parameters
#### Request Body
- **name** (string) - Required - The name of the environment variable.
- **value** (string) - Required - The value of the environment variable.
```

--------------------------------

### Workflow Script: Health Check

Source: https://context7.com/geekforbrains/harbour/llms.txt

A bash script example for a workflow that checks the health of an external API by monitoring its HTTP status code. Exits with 0 for success, 2 for failure.

```bash
# ~/.harbour/workflows/health_check.sh
# Workflow-only job: workflow_command = "bash health_check.sh", workflow_only = true
#!/bin/bash
status=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health)
if [ "$status" = "200" ]; then
  echo "API healthy: returned $status"
  exit 0
else
  echo "API unhealthy: returned $status" >&2
  exit 2  # non-zero, non-77 → run marked failed
fi
```

--------------------------------

### Connect Remote Harbour Agent Runner

Source: https://github.com/geekforbrains/harbour/blob/main/README.md

Installs Harbour dependencies and connects a remote agent runner. This is used when a job needs to run on a specific machine different from the Harbour server.

```bash
git clone https://github.com/geekforbrains/harbour.git
cd harbour
npm install
```

```bash
npm run harbour -- agent connect <blob>
```

--------------------------------

### Organize work into a project

Source: https://github.com/geekforbrains/harbour/blob/main/ADMIN_GUIDE.md

These API calls are used to create a new project and to link various resources like agents, jobs, documentation, and environment variables to it.

```APIDOC
## POST /api/projects

### Description
Creates a new project.

### Method
POST

### Endpoint
/api/projects

## PATCH /api/projects/:id

### Description
Links agents, jobs, docs, env vars, and databases to an existing project.

### Method
PATCH

### Endpoint
/api/projects/:id

### Parameters
#### Request Body
- **agents** (array) - Optional - A list of agent IDs to link to the project.
- **jobs** (array) - Optional - A list of job IDs to link to the project.
- **docs** (array) - Optional - A list of document IDs to link to the project.
- **envVars** (array) - Optional - A list of environment variable IDs to link to the project.
- **databases** (array) - Optional - A list of database IDs to link to the project.
```