Synced from docs/llm-agent-reference-compact.md in the Computalot monorepo.

Computalot is a distributed compute platform. Submit jobs, get structured JSON results. GPU and CPU workers.

Private beta — running jobs requires an admin-issued API key or admin-whitelisted wallet session. Discovery is public. We’re actively building and want your feedback.

If you do not already have beta access, join the waitlist at / or ask an admin to provision access.

API keys are admin-issued during beta.

Base URL: https://dev.computalot.com

• https://dev.computalot.com/skill.md — install this skill to get started
• https://dev.computalot.com/llms.txt — this compact reference
• https://dev.computalot.com/llms-full.txt — full reference with tutorials
• https://dev.computalot.com/api/v1/docs — machine-readable JSON index
• https://dev.computalot.com/docs — human docs

Feedback — Report Bugs & Request Features

This is beta software. Please report bugs, request features, and share ideas:

curl -sS -X POST https://dev.computalot.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -d '{"type": "bug", "title": "Brief summary", "description": "What happened, what you expected"}'

Types: bug, feature_request, provisioning, job_type_request. No auth required.

Two Paths

Sealed Recipes — Platform compute primitives. No project setup. Send typed payloads, get results.

Projects — Bring your own code. Create a project, push a tarball, submit jobs with runner_command.

Auth

# API key (admin-issued during beta)
export TOKEN="flk_..."
 
# Wallet session (admin-whitelisted wallets)
# 1. POST /api/v1/auth/wallet/challenge
# 2. Sign challenge.message with your wallet
# 3. POST /api/v1/auth/wallet/verify → returns fls_... token
 
# All protected endpoints:
Authorization: Bearer $TOKEN

No auth required: /health, /docs, /llms.txt, /llms-full.txt, /api/v1/docs/*, POST /api/v1/feedback, POST /api/v1/auth/wallet/challenge, POST /api/v1/auth/wallet/verify.

GET /metrics is operator-gated: local requests, admin auth, or the dedicated metrics token only.

Sealed Recipe Quickstart

# 1. List recipes
curl -sS -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/recipes
 
# 2. Submit a recipe job
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.computalot.com/api/v1/recipes/packing/jobs \
  -d '{"payload": {"operation": "eval", "candidate": [0.12, 0.31, 0.88]}, "timeout_s": 300}'
 
# 3. Read results
curl -sS -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/results/<job_id>

Recipe jobs don’t need type or runner_command — the recipe provides both.

Recipe Catalog

Inspect schema before submitting: GET /api/v1/recipes/:name returns payload_schema, operations, artifact_inputs.

Project Quickstart

# 1. Create project
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.computalot.com/api/v1/projects \
  -d '{"name": "my-proj", "remote_dir": "/root/projects/my-proj"}'
 
# 2. Upload tarball (raw binary, NOT multipart)
tar czf code.tar.gz Dockerfile computalot.project.json script.py
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  --data-binary @code.tar.gz \
  https://dev.computalot.com/api/v1/projects/my-proj/push
 
# 3. Submit job immediately after push
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.computalot.com/api/v1/jobs \
  -d '{"type": "structured_runner", "runner_command": ["python3", "script.py"], "payload": {"test": true}, "project": "my-proj", "timeout_s": 120}'
 
# 4. Optional: prepare currently available workers ahead of time
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://dev.computalot.com/api/v1/projects/my-proj/init
 
# 5. Inspect published vs warm state
curl -sS -H "Authorization: Bearer $TOKEN" \
  https://dev.computalot.com/api/v1/projects/my-proj/status
 
# 6. Results
curl -sS -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/results/<job_id>

Project Lifecycle & Readiness

• Readiness is active revision truth, not machine-count truth
• After POST /api/v1/projects/:name/push, a successful response can include tarball_diff
• Use GET /api/v1/projects/:name/status for top-level readiness and GET /api/v1/projects/:name/status/details for diagnostics + recovery guidance
• can_accept_new_jobs: true means the latest revision is published and can be submitted immediately
• ready_for_jobs can stay false after push while the first job or an optional /init prepares runtime

Job Types

Default to structured_runner unless another type clearly fits.

Runner Protocol

Your script receives input and writes output via environment variables:

• $COMPUTALOT_TASK_PAYLOAD — path to JSON input file. Read this.
• $COMPUTALOT_TASK_RESULT — path to write JSON output. Computalot reads this after exit.
• $COMPUTALOT_ARTIFACT_DIR — directory for output files. Auto-uploaded on completion.
• Exit 0 = success. Non-zero = failure.
• Progress: print COMPUTALOT_PROGRESS:{"epoch":5,"loss":0.23} to stdout.

import json, os
payload = json.load(open(os.environ['COMPUTALOT_TASK_PAYLOAD']))
result = {'score': 0.95, 'model': payload['model']}
json.dump(result, open(os.environ['COMPUTALOT_TASK_RESULT'], 'w'))

Fan-Out

Split one job into parallel tasks:

By list values — one task per item:

{"fan_out": {"by": "models"}, "payload": {"models": ["gpt4", "claude", "llama"]}}

By explicit items — custom payload per task:

{"fan_out": {"items": [{"params": [0.1, 0.5]}, {"params": [0.2, 0.4]}]}}

By chunks — split a numeric range:

{"fan_out": {"chunks": 20, "range_field": "total_seeds", "total": 10000}}

These are mutually exclusive. Add batch_size to group tiny items into one task. Merge strategies: collect (default), keyed, weighted_avg.

Choose exactly one fan-out shape per submit. Mixed shapes are rejected with 422.

Common Job Fields

Long ML jobs: use _artifacts.download for one-off large inputs, manifest data_sources for immutable remote weights/datasets, and manifest cache_mounts for writable runtime caches. hf-mount only applies to manifest-declared Hugging Face data_sources, not arbitrary runner-side downloads.

Results & Streaming

# Terminal results
curl -sS -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/results/<job_id>
 
# Per-task details and progress
curl -sS -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/jobs/<job_id>/tasks
 
# Stdout/stderr
curl -sS -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/jobs/<job_id>/output
 
# SSE stream (one job)
curl -sS -N -H "Authorization: Bearer $TOKEN" https://dev.computalot.com/api/v1/jobs/<job_id>/stream
 
# SSE stream (multiple jobs)
curl -sS -N -H "Authorization: Bearer $TOKEN" "https://dev.computalot.com/api/v1/jobs/watch?ids=<id1>,<id2>"

Job lifecycle: planning → queued → running → completed | partial | failed | cancelled

Debug failures: GET /api/v1/jobs/:id for error and recommended_action, GET /api/v1/jobs/:id/tasks for per-task diagnostics.

During retries, GET /api/v1/jobs/:id/tasks and GET /api/v1/jobs/:id/output preserve the most recent failed attempt’s diagnostics until the current attempt emits its own output.

Public task/result payloads keep the submitted task contract visible, but redact provider IDs, raw runtime paths, and image refs/digests.

Billing

• Check balance: GET /api/v1/account/balance
• Jobs reserve a hold on submission, settle to actual usage on completion
• Project init is free but requires $5 available balance
• Fund via x402: POST /api/v1/account/quotes/topup → pay → POST /api/v1/account/quotes/:id/pay/x402
• If a request returns 402, fund the account and retry the same request

Billing truth lives on GET /api/v1/account/balance, GET /api/v1/account/holds, and GET /api/v1/account/ledger.

Use GET /api/v1/account/quotes to inspect open top-up and shortfall quotes before retrying blocked work.

If project init or job submit returns a shortfall quote, fund the account and retry POST /api/v1/projects/:name/init or retry the same submit request to POST /api/v1/jobs.

Python SDK & CLI

python3 -m pip install --user --break-system-packages \
  https://dev.computalot.com/docs/downloads/computalot-0.2.0-py3-none-any.whl
export PATH="$HOME/.local/bin:$PATH"

from computalot import ComputalotClient
client = ComputalotClient(controller_url="https://dev.computalot.com", token="YOUR_TOKEN")
recipes = client.list_recipes()
jobs = client.list_jobs(limit=5)
print(len(recipes.get("recipes", [])))
print(len(jobs.get("jobs", [])))

computalot docs --llm
computalot jobs --limit 5
computalot job <job_id>

Endpoint Reference

Recipes

Jobs

Billing

Results & Artifacts

Projects

Public (no auth)

Ops (operator-facing)