---
title: "Create a harness [write]"
method: POST
path: "/harnesses"
tags: ["harnesses"]
---

# Create a harness \[write\]

`POST /harnesses`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/harnesses`
- Auth: HTTP bearer

Creates a workspace harness with the given handle, name and profile. After creating, add a version with POST /harnesses/{id}/versions, then promote it with POST /harnesses/{id}/versions/{v}/current before creating agents that reference it. Returns 404 when the WORKSPACE_HARNESSES feature switch is off for this workspace. Returns 503 not_migrated when the backing tables are not yet present.

## Request body

- CreateHarness
  - `handle` string, required
  - `name` string, required
  - `profile` object, required
    - `id` string, required
    - `name` string, required
    - `version` string, required
    - `distribution` union
      - object
      - object
        - `oci` object, required
          - `image` string, required
    - `auth_command` string[]
    - `bundled_mcp_servers` object[]
    - `configuration_files` object[]
    - `credential_args` object
    - `graceful_exit_timeout_seconds` number
    - `home_directories` string[]
    - `managed_model_id_template` string
    - `native_provider_setup` object
    - `pipeline` string
    - `prerequisites` object
    - `request_timeout_seconds` number
    - `requirements` string[]
    - `session_close_before_exit` boolean
    - `session_config_options` object
    - `session_load_supported` boolean
    - `session_parameters` object
    - `subscription_files` boolean
    - `docker_target` string
    - `tools` object[]
      - `id` string, required
      - `kind` string, required
      - `title` string
      - `requires` object
    - `features` string[]
    - `placement` 'in_sandbox' | 'remote'
  - `model_billing` 'gateway' | 'external'

## Response `201`

Created

- object
  - `harness` Harness, required
    - `id` string, required: hrn_… — the public id
    - `handle` string, required: Short slug within the workspace (e.g. my-harness)
    - `name` string, required
    - `profile` HarnessProfile, required: The runtime description of a workspace harness: the distribution spec (npx, uvx or binary), optional auth command, bundled MCP servers, tools, features and other catalog fields the installer reads when it builds the template image.
      - `id` string, required
      - `name` string, required
      - `version` string, required
      - `distribution` union
        - object
        - object
          - `oci` object, required
            - `image` string, required
      - `auth_command` string[]
      - `bundled_mcp_servers` object[]
      - `configuration_files` object[]
      - `credential_args` object
      - `graceful_exit_timeout_seconds` number
      - `home_directories` string[]
      - `managed_model_id_template` string
      - `native_provider_setup` object
      - `pipeline` string
      - `prerequisites` object
      - `request_timeout_seconds` number
      - `requirements` string[]
      - `session_close_before_exit` boolean
      - `session_config_options` object
      - `session_load_supported` boolean
      - `session_parameters` object
      - `subscription_files` boolean
      - `docker_target` string
      - `tools` object[]
        - `id` string, required
        - `kind` string, required
        - `title` string
        - `requires` object
      - `features` string[]
      - `placement` 'in_sandbox' | 'remote'
    - `model_billing` 'gateway' | 'external', required: gateway: model calls are billed through the platform wallet. external: the harness manages billing itself.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/harnesses/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)