---
name: computalot
description: Use Computalot distributed GPU/CPU compute — submit jobs, get structured results. Beta.
metadata:
  short-description: Computalot distributed compute (beta)
triggers:
  - computalot
  - distributed compute
  - submit job
  - computalot job
  - computalot run
  - gpu compute
  - run on gpu
---

# Computalot (Beta)

Computalot is a distributed compute platform. You submit jobs, Computalot runs them on GPU/CPU workers, and you get structured JSON results back.

**Private beta.** You need either an admin-issued API key (`flk_...`) or an admin-whitelisted wallet session (`fls_...`) to run jobs. Discovery endpoints are public.

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

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

## Supported Beta Access Today

- Admin-issued API key (`flk_...`)
- Admin-whitelisted wallet session (`fls_...`)
- Admin-whitelisted wallets can exchange a verified challenge for an `fls_...` session
- Waitlist at `/` if you need beta access

## Report Bugs & Request Features

We're actively improving Computalot during beta. Please report any issues or ideas:

```bash
curl -sS -X POST https://computalot.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -d '{"type": "bug", "title": "Brief summary", "description": "Details..."}'
```

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

## Two Ways to Use It

**Sealed Recipes** — Platform compute primitives. No code upload needed. Send a typed payload, get results.

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

## Quick Start: Sealed Recipe

```bash
export TOKEN="flk_..."

# 1. List recipes
curl -sS https://computalot.com/api/v1/recipes -H "Authorization: Bearer $TOKEN"

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

# 3. Get results
curl -sS https://computalot.com/api/v1/results/<job_id> -H "Authorization: Bearer $TOKEN"
```

## Quick Start: Your Own Code

```bash
export TOKEN="flk_..."

# 1. Create project
curl -sS -X POST https://computalot.com/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-proj", "remote_dir": "/root/projects/my-proj"}'

# 2. Upload code (raw binary, NOT multipart)
tar czf code.tar.gz Dockerfile computalot.project.json script.py
curl -sS -X POST https://computalot.com/api/v1/projects/my-proj/push \
  -H "Authorization: Bearer $TOKEN" --data-binary @code.tar.gz

# 3. Initialize (async, then poll)
curl -sS -X POST https://computalot.com/api/v1/projects/my-proj/init \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"
curl -sS https://computalot.com/api/v1/projects/my-proj/status \
  -H "Authorization: Bearer $TOKEN"
# Wait for ready_for_jobs: true

# 4. Submit a job
curl -sS -X POST https://computalot.com/api/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "structured_runner", "runner_command": ["python3", "script.py"], "payload": {"test": true}, "project": "my-proj", "timeout_s": 120}'

# 5. Get results
curl -sS https://computalot.com/api/v1/results/<job_id> -H "Authorization: Bearer $TOKEN"
```

## Auth

```
Authorization: Bearer <token>
```

- API key: `flk_...` (admin-issued during beta)
- Wallet session: `fls_...` (`POST /api/v1/auth/wallet/challenge` → sign → `POST /api/v1/auth/wallet/verify`)

No auth needed: `/health`, `/docs`, `/llms.txt`, `/api/v1/docs`, `/api/v1/feedback`

## Python SDK & CLI

Install the published beta wheel from a public URL:

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

First authenticated probe after you receive an API key or wallet session:

```bash
export COMPUTALOT_CONTROLLER_URL="https://computalot.com"
export COMPUTALOT_API_TOKEN="flk_..."

computalot docs --llm
computalot jobs --limit 5
```

```python
from computalot import ComputalotClient

client = ComputalotClient(
    controller_url="https://computalot.com",
    token="flk_...",
)

recipes = client.list_recipes()
jobs = client.list_jobs(limit=5)
print(len(recipes.get("recipes", [])))
print(len(jobs.get("jobs", [])))
```

## Billing & Retry Guidance

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. 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`.

## Full Reference

Read the complete API docs before starting complex work:

- `/llms.txt` — compact reference for agents
- `/llms-full.txt` — full reference with tutorials
- `/api/v1/docs` — machine-readable JSON index
- `/docs` — human documentation site