Taskron

Share your idle compute power and run jobs across your network of machines.

Taskron lets you turn spare laptops, desktops, and servers into a distributed job execution system. Submit simple jobs via API and have them run on any available machine in your pool. Perfect for batch processing, data analysis, or running background tasks across your local network.

Authentication

Taskron uses a two-level auth model:

• Admin key — used by the operator to manage tokens. Required for POST /admin/tokens and GET /admin/tokens.
• Single-use tokens — issued by the admin, given to callers. Each token can submit exactly one job and is then permanently consumed.

This ensures you control who can submit jobs, and each submission is explicitly authorized.

Quick Start

1. Build Taskron

git clone https://github.com/your-username/taskron
cd taskron
mise build

Requires Go 1.21+ and Mise for task management.

2. Start the Coordinator

Run this on one machine (your main server):

./bin/taskron -mode coordinator -port 8080

The coordinator manages the job queue and tracks all worker nodes.

3. Add Worker Nodes

Run this on any machine you want to contribute compute power:

./bin/taskron -mode worker -coordinator http://COORDINATOR_IP:8080

Workers automatically register themselves and start accepting jobs when idle.

4. Get an Admin Key

When the coordinator starts without --admin-key, it generates one and prints it:

========================================
  ADMIN KEY (save this): admin-<hex>
========================================

You can also set a fixed key:

./bin/taskron -mode coordinator -port 8080 --admin-key mysecretkey

5. Generate a Token

Each job submission requires a single-use token. Generate one with the admin key:

curl -X POST http://COORDINATOR_IP:8080/admin/tokens \
  -H "Authorization: Bearer admin-<your-admin-key>"

Response:

{
  "success": true,
  "data": {
    "id": "tkn-a1b2c3d4e5f6",
    "created_at": "2026-04-03T10:00:00Z"
  }
}

6. Submit a Job

Pass the token as a Bearer token when submitting:

curl -X POST http://COORDINATOR_IP:8080/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tkn-a1b2c3d4e5f6" \
  -d '{
    "command": "echo",
    "args": ["Hello from distributed compute!"]
  }'

The token is consumed immediately — reusing it returns 401 token already used. Your job will run on the next available worker node.

Usage Examples

Run a Python script

curl -X POST http://localhost:8080/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tkn-<token>" \
  -d '{
    "command": "python3",
    "args": ["-c", "print(sum(range(100)))"],
    "timeout_secs": 30
  }'

Process a file

curl -X POST http://localhost:8080/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tkn-<token>" \
  -d '{
    "command": "ffmpeg",
    "args": ["-i", "input.mp4", "-vf", "scale=640:360", "output.mp4"],
    "timeout_secs": 600
  }'

Check system status

curl http://localhost:8080/health

Returns queue depth, active nodes, and job counts.

API Endpoints

Method	Path	Auth	Description
POST	/jobs	Bearer token	Submit a job (token consumed on use)
GET	/jobs	—	List all jobs
GET	/jobs/{id}	—	Get job status
GET	/nodes	—	List worker nodes
GET	/health	—	System status
POST	/admin/tokens	Admin key	Generate a new single-use token
GET	/admin/tokens	Admin key	List all tokens and their status

Job Options

Field	Type	Description
command	string	Executable to run (required)
args	[]string	Command arguments
env	map[string]string	Environment variables
timeout_secs	int	Max runtime in seconds (default: 60)
max_retries	int	Retry attempts on failure (default: 0)

How It Works

1. Coordinator runs on one machine and manages the job queue
2. Workers connect to the coordinator and report their availability
3. When you submit a job, the coordinator assigns it to an idle worker
4. The worker executes the job and reports the result back
5. If a worker goes offline, jobs are automatically reassigned

Requirements

• Go 1.21+
• Network connectivity between coordinator and workers
• Executables you want to run must be available on worker machines

Contributing Compute

Want to share your idle compute? Just run a worker:

./bin/taskron -mode worker -coordinator http://YOUR_COORDINATOR:8080

Your machine will automatically join the pool and start processing jobs when idle.