How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/iii-hq/iii --skill iii-getting-startedBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Getting Started with iii
iii replaces your API framework, task queue, cron scheduler, pub/sub, state store, and observability pipeline with a single engine and one primitive, the Function. Workers host functions, any worker runs a function with call, and iii.observe(a, b) means "when a runs, b runs".
Step 1: Install the Engine
curl -fsSL https://iii.dev/registry/install/iii/latest.sh | shOn Windows, in PowerShell:
irm https://iii.dev/registry/install/iii/latest.ps1 | iexVerify it installed:
iii --versionStep 2: Create a Project
iii project init my-app # barebones project
iii project init my-app -t harness # or: the harness template (agent + console UI)
cd my-appiii project init --learn-iii scaffolds the harness template and starts it in one step; the installer offers the same when you answer "y" at its prompt. iii project init --template quickstart scaffolds the Quickstart with a Python and a TypeScript worker.
Step 3: Start the Project
iii compose --namespace dev --up --file worker-compose.yamlThe file's engine: section starts the engine; containers: starts project workers. The engine commonly listens on ws://localhost:49134. Keep this foreground supervisor running.
--namespace dev names the daemon and becomes III_NAMESPACE for every worker it starts, so your workers register and call each other in dev; that is why the iii call commands below pass -n dev. Engine-owned functions (engine::*, configuration::*) stay in default, and SDK calls to them resolve there without a namespace (see iii-sdk-reference).
Step 4: Install the SDK
Pick your language:
# TypeScript / Node.js
pnpm add iii-sdk @iii-dev/helpers
# Python
pip install iii-sdk iii-helpers
# Rust
cargo add iii-sdk iii-helpersStep 5: Write Your First Worker
The worker registers hello::greet and observes http::on-request with a route: each POST /hello request runs hello::greet, and its return value is the HTTP response.
TypeScript
import { registerWorker } from "iii-sdk";
import { Logger } from "@iii-dev/helpers/observability";
const iii = registerWorker(process.env.III_URL ?? "ws://localhost:49134");
iii.registerFunction(
"hello::greet",
async (req: { body?: { name?: string } }) => {
const logger = new Logger();
const name = req.body?.name ?? "world";
logger.info("Greeting user", { name });
return { status_code: 200, body: { message: `Hello, ${name}!` } };
},
{ description: "Greet a user by name" },
);
iii.observe(
{ function_id: "http::on-request", args: { method: "POST", path: "/hello" } },
"hello::greet",
);Python
from iii import register_worker, InitOptions
from iii_helpers.observability import Logger
iii = register_worker(address="ws://localhost:49134", options=InitOptions(worker_name="hello-worker"))
def greet(req):
logger = Logger()
body = req.get("body") or {}
name = body.get("name", "world") if isinstance(body, dict) else "world"
logger.info("Greeting user", {"name": name})
return {"status_code": 200, "body": {"message": f"Hello, {name}!"}}
iii.register_function("hello::greet", greet, description="Greet a user by name")
iii.observe(
{"function_id": "http::on-request", "args": {"method": "POST", "path": "/hello"}},
"hello::greet",
)Rust
use iii_sdk::{register_worker, InitOptions, RegisterFunction, Source};
use iii_helpers::observability::Logger;
use serde_json::json;
let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());
iii.register_function(
"hello::greet",
RegisterFunction::new(|req: serde_json::Value| -> Result<serde_json::Value, iii_sdk::Error> {
let logger = Logger::new();
let name = req["body"]["name"].as_str().unwrap_or("world");
logger.info("Greeting user", Some(json!({ "name": name })));
Ok(json!({ "status_code": 200, "body": { "message": format!("Hello, {}!", name) } }))
}).description("Greet a user by name"),
);
iii.observe(
Source::function("http::on-request").args(json!({ "method": "POST", "path": "/hello" })),
"hello::greet",
);To run a function whenever another one runs, observe it the same way: iii.observe("hello::greet", "audit::record") (see iii-observe).
Step 6: Test It
http::on-request comes from the http worker. Add it once through the running Compose daemon, then call your endpoint:
iii call -n dev compose::add worker=httpcurl -X POST http://localhost:3111/hello \
-H "Content-Type: application/json" \
-d '{"name": "iii"}'Expected response:
{ "message": "Hello, iii!" }Add Existing Workers
To add a capability that already exists, browse https://workers.iii.dev/ and add it through the running Compose daemon:
iii call -n dev compose::add worker=state
iii call -n dev compose::add worker=queue
iii call -n dev compose::add worker=image-resize@0.1.2compose::add resolves dependencies, writes exact versions to worker-compose.yaml, and restarts the affected project. A local worker can be declared as a path:// container or added by path.
Install Agent Skills
Get all iii skills for your AI coding agent:
npx skills add iii-hq/iii/skillsSkills teach your agent the top-level iii model: functions (call and observe), the workers that host them, registry access, SDKs, engine configuration, architecture patterns, and error handling. Worker-backed capabilities live with the worker docs and registry entries.
Adapting This Pattern
- Add more functions to the same worker: each gets its own
registerFunction, plus anobserve
for each event that should run it
- Use
::separator for function IDs to namespace them:orders::create,orders::validate - Run a function on a schedule with `iii.observe({ function_id: 'cron::on-tick', args: {
expression: '0 0 9 ' } }, 'reports::daily') (7-field: sec min hour day month weekday year; needs the cron` worker)
- Run a function for each queue message with `iii.observe({ function_id: 'queue::on-message', args:
{ topic: 'my-queue' } }, 'jobs::process') (needs the queue` worker)
- Use
iii.call()to invoke other functions from within a function - Use
iii.observe("hello::greet", "audit::record")to run a registered function after every
successful call of another one (see iii-observe)
- Use
state::get/state::setto persist data across function calls - Use
iii call -n <daemon> compose::add worker=<name>when the capability already exists in the
worker registry
Recommended Next Steps
After getting your first worker running:
- Register functions, call them, and create workers: see
iii-core-primitives - Observe functions and engine events: see
iii-observe - Choose the right SDK APIs: see
iii-sdk-reference - Configure the engine: see
iii-engine-config - Explore backend patterns: see
iii-architecture-patterns - Handle failures well: see
iii-error-handling
Key Resources
- Quickstart Guide
- SDK Reference: Node.js
- SDK Reference: Python
- SDK Reference: Rust
- Compose
- Configuration
- Console
- Observers
- Upgrading from 0.25.x
- Every docs page is also available as Markdown by adding a
.mdsuffix to its URL.
Pattern Boundaries
- For function registration and calls, worker creation, worker registry access, built-in source
functions, invocation modes, and channels, prefer iii-core-primitives
- For observers, filters, engine events, event sources, and upgrading 0.25 code, prefer
iii-observe
- For language-specific SDK APIs, prefer
iii-sdk-reference - For engine configuration, prefer
iii-engine-config - For worker-backed HTTP, cron, queue, pubsub, state, stream, and observability behavior, use the matching worker page on https://workers.iii.dev/
- Stay with
iii-getting-startedfor installation, initial setup, and first-worker guidance
When to Use
- Use this skill when the task is about installing iii, creating a new project, or writing a first
worker.
- Use it when the request asks for setup help, quickstart guidance, or getting started with iii.
Boundaries
- Never use this skill as a generic fallback for unrelated tasks.
- You must not apply this skill when a more specific iii skill is a better fit.
- Always verify environment and safety constraints before applying examples from this skill.