Developer docs Getting started

Overview

allybuild exposes three integration surfaces: the task script runtime, the platform API consumed through the SDK, and an OpenAI-compatible LLM gateway.

What you can integrate

Every allybuild task runs inside an isolated sandbox with the AllyBuild SDK preinstalled. From inside a task script you can:

report phases and progress back to the platform in real time
create, wait for, and inspect other tasks in the same project
read the agent roster, workspaces, and task memories
call MCP tools exposed by the project
persist cross-run state with reactive stores
react to project-status changes with background services
query the project knowledge base (OKF) for grounded context
call LLMs through the OpenAI-compatible gateway without managing API keys

Core concepts

Concept	What it is
Meta-task	The reusable job definition: phases, params schema, script, owning agent
Task instance	One execution of a meta-task, with status, current phase, and progress
Agent	A named team member: model, provider, skills, and the meta-tasks it owns
Workspace	The sandbox directory a task runs against, shared by the project team
Memory	Distilled lessons from previous runs, searchable per meta-task
Approval gate	A checkpoint where a task parks in pending_approval until a human decides
Cron	A schedule that dispatches a meta-task on a cron expression
Service	A long-running background process bound to a workspace

The task script contract

A task script is a single task_script.py or task_script.ts file uploaded to the task slot at /workspace/.allybuild/slots/{task_id}/ — the platform materializes the workflow module and a starter entry next to it. It runs from the workspace directory with a 300-second execution budget per run. Export a run entry point — everything else comes from the workflow module:

def run(params: dict, reporter) -> None:
    reporter.set_phase("Fetching")
    reporter.set_progress(30)

    rows = fetch_rows(params["source"])
    reporter.set_progress(90)
    write_report(rows)

TypeScript mirrors the contract with camelCase reporter methods:

export async function run(
  params: Record<string, unknown>,
  reporter: { setPhase: (s: string) => void; setProgress: (n: number) => void },
) {
  reporter.setPhase("Fetching")
  reporter.setProgress(30)
}

Injected environment

Variable	Description
TASK_ID	The running task instance id
PROJECT_ID	Owning project id — scopes all API reads and writes
TASK_JWT	Bearer credential for the platform API and the LLM gateway
ALLYBUILD_API_URL	Platform API base URL, including the /api prefix
TASK_PARAMS	JSON-encoded params passed to run()
ALLYBUILD_PROJECT_TOKENS	JSON map of project-scoped tokens
BG_SERVICE_ID	Set when the script runs as a background service
ALLYBUILD_WORKSPACE_ID	Workspace bound to a background service, if any

Quickstart: your first task

This Python script reads params, calls the LLM gateway, reports progress, and spawns a follow-up task:

from openai import OpenAI

def run(params: dict, reporter) -> None:
    reporter.set_phase("Summarize")

    gateway = f"{ALLYBUILD_API_URL.removesuffix('/api')}/v1"
    llm = OpenAI(base_url=gateway, api_key=TASK_JWT)
    resp = llm.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": f"Summarize: {params['text']}"}],
    )
    summary = resp.choices[0].message.content
    reporter.set_progress(60)

    reporter.set_phase("Dispatch review")
    tid = create_task(
        "reviewer",
        name=f"review-{TASK_ID[:8]}",
        params={"summary": summary},
    )
    return {"summary": summary, "review_task": tid}

Install the SDK locally

pip install allybuild-sdk   # Python 3.10+
npm install @allybuild/sdk   # Node.js >= 18

Continue with Authentication, then the guides — Tasks & scheduling, Agents & skills, State & memory, Publish & fork — and the Python or TypeScript SDK reference for the full surface.