Hydracept

Quick Start

Hydracept is an execution control plane for software and agents that need external capabilities. Games and media are important examples.

Discovery, quoting, durable jobs, artifacts, receipts, and recoverable project history. BYOK is free; managed inference adds a 6% service fee. Eligible durable text jobs use deferred processing at 50% of standard token rates.

5-minute path

For one asset: python -m hydracept run image.generate.v1 --prompt "..." --json (composes init). For a full walkthrough, see 5-minute game asset. One-off tasks are supported — a single capability call does not require an integration commitment.

Activate

Pick one:

  1. CLI bootstrap (recommended): pip install -U hydracept then python -m hydracept init --apply --yes --json. Init infers the current git/workspace project when you are already signed in. Browser project selection is only required when that inference is ambiguous.
  2. Studio (browser): app.hydracept.com/login — sign in with GitHub or Google, complete onboarding, then generate in Studio. Manage plans at Studio Billing.
  3. Agents / headless: python -m hydracept init --apply --yes --json (or use an existing key out of band with HYDRACEPT_API_KEY).

For coding agents, interaction_required is a hard human boundary. If presentation.agentAction is present_and_yield and stdio MCP exposes hydracept_interaction_surface, invoke that surface once with the supplied context and stop the turn. Otherwise present action.url verbatim. In either case, stop until the human completes activation; only then run afterCompletion.command / --wait.

See Authentication for workspace files (.hydracept/project.json, secrets, lazy BYOK) and CI mode (init --apply --yes --json --ci).

Public API: https://api.hydracept.com

Configuration directory (CLI): .hydracept/

Environment variables: HYDRACEPT_API_URL, HYDRACEPT_API_KEY, HYDRACEPT_PROJECT, HYDRACEPT_ENVIRONMENT

BYOK: Your Hydracept API key authenticates your application, while your provider key pays for inference. Run python -m hydracept smoke (trial budget or BYOK — a real image job) before connecting BYOK — see Connections / BYOK and Billing & plans.

CLI


pip install -U hydracept

# Prefer the module form if `hydracept` is not on PATH (common on Windows):
python -m hydracept init                              # human — opens connect URL when needed
python -m hydracept init --apply --yes --json         # agents
python -m hydracept init --apply --yes --json --ci    # CI (setup grants)
python -m hydracept doctor
python -m hydracept smoke
python -m hydracept verify
python -m hydracept agent-context

configure and quickstart are deprecated aliases for init. Device login (python -m hydracept login) still works for advanced flows.

SDKs

The Python SDK and CLI are available now:


pip install -U hydracept
python -m hydracept --help

The TypeScript SDK is also available:


npm install @hydracept/sdk

.NET SDK


dotnet add package Hydracept.Client

Discover capabilities


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  https://api.hydracept.com/v1/capabilities

The live catalog is GET /v1/capabilities (or python -m hydracept agent-context). Do not freeze a launch-key list from this README.

See Capabilities for how capability keys work.

For image production (Sheet & Slice, transparent output, variants), see Image production.

For Unity 6 Editor integration (generate, sheet slice, import with provenance), see Unity integration.

Submit a durable job


JOB_JSON=$(curl -sS -X POST \
  -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "productId": "my-product",
      "projectId": "cpr_...",
      "environment": "development"
    },
    "input": { "prompt": "cute slime icon" },
    "execution": { "executionPreference": "automatic" },
    "idempotencyKey": "demo-1"
  }' \
  https://api.hydracept.com/v1/capabilities/image.generate.v1/jobs)

echo "$JOB_JSON"
JOB_ID=$(printf '%s' "$JOB_JSON" | python -c "import sys,json; print(json.load(sys.stdin)['jobId'])")

The submit response is a HydraceptJob object. Use jobId from that payload for poll and receipt calls.

Poll the job


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  https://api.hydracept.com/v1/jobs/$JOB_ID

Poll until status is succeeded, failed, or canceled.

Fetch the receipt


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  https://api.hydracept.com/v1/jobs/$JOB_ID/receipt

Find and inspect later

If an agent no longer has the ID—or a user simply says “the last job failed”—query project history instead of asking the human to find it:


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  "https://api.hydracept.com/v1/projects/cpr_.../jobs?outcome=failed&limit=10"

The list is prompt-free. Once the relevant job is identified, intentionally inspect only that job with GET /v1/jobs/{jobId}. MCP provides the shorter agent loop:


hydracept_jobs_find(intent="failed")
→ hydracept_job_inspect(job_id)

For prior successful outputs use intent="reusable"; Hydracept highlights an explicitly selected artifact when one exists. A retry always uses a new idempotency key.

See Durable Jobs & Receipts for filters, artifacts, inspection, and outputs.

Next