iii-getting-started

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

sdk/packages/node/iii/local.yml

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

Audit 0.4.1 · source sha 872770b7cf06 · 29 Oct 2026Report an issue or request a re-scan

• Publisheriii-hq GitHub organizationOwner of the repository this skill is read from
• Source folderiii-hq/iii/skills/iii-getting-startedThe exact folder we audited
• LicenceNot declaredAs the repository states it
• Commit pinned for this verdict872770b7cf06A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Install the iii engine, set up your first worker, and get a working backend running. Use when a user wants to start a new iii project, install the SDK, or needs help with initial setup and configuration.

---
name: iii-getting-started
description: >-
  Install the iii engine, set up your first worker, and get a working backend running. Use when a
  user wants to start a new iii project, install the SDK, or needs help with initial setup and
  configuration.
---

# 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 three primitives: **Function**, **Trigger**, **Worker**.

## Step 1: Install the Engine

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
```

Verify it installed:

```bash
iii --version
```

## Step 2: Create a Project

```bash
iii project init my-app              # barebones project
iii project init my-app -t harness   # or: the harness template (agent + console UI)
cd my-app
```

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

```bash
iii compose --namespace dev --up --file worker-compose.yaml
```

The 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 trigger` 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:

```bash
# TypeScript / Node.js
pnpm add iii-sdk @iii-dev/helpers

# Python
pip install iii-sdk iii-helpers

# Rust
cargo add iii-sdk iii-helpers
```

## Step 5: Write Your First Worker

### TypeScript

```typescript
import { registerWorker, TriggerAction } 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 (input) => {
    const logger = new Logger();
    const name = input?.name ?? "world";
    logger.info("Greeting user", { name });
    return { message: `Hello, ${name}!` };
  },
  { description: "Greet a user by name" },
);

iii.registerTrigger({
  type: "http",
  function_id: "hello::greet",
  config: { api_path: "/hello", http_method: "POST" },
});
```

### Python

```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(data):
    logger = Logger()
    name = data.get("name", "world") if isinstance(data, dict) else "world"
    logger.info("Greeting user", {"name": name})
    return {"message": f"Hello, {name}!"}

iii.register_function("hello::greet", greet, description="Greet a user by name")
iii.register_trigger({"type": "http", "function_id": "hello::greet", "config": {"api_path": "/hello", "http_method": "POST"}})
```

### Rust

```rust
use iii_sdk::{register_worker, InitOptions, RegisterFunction};
use iii_sdk::protocol::RegisterTriggerInput;
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(|input: serde_json::Value| -> Result<serde_json::Value, iii_sdk::Error> {
        let logger = Logger::new();
        let name = input["name"].as_str().unwrap_or("world");
        logger.info("Greeting user", Some(json!({ "name": name })));
        Ok(json!({ "message": format!("Hello, {}!", name) }))
    }).description("Greet a user by name"),
);

// Deprecated since 0.25, still how you bind to the http worker: compiles with a warning.
#[allow(deprecated)]
iii.register_trigger(RegisterTriggerInput::new(
    "http",
    "hello::greet",
    json!({ "api_path": "/hello", "http_method": "POST" }),
))?;
```

`registerTrigger` logs a one-time deprecation warning in iii 0.25. It keeps working, and it is still
the way to bind to the `http`, `cron`, queue, `state`, `stream`, and pub/sub workers, which have not
moved to source functions yet. To run a function after another one, use `iii.observe` (see
`iii-observe`).

## Step 6: Test It

The `http` trigger type comes from the `http` worker. Add it once through the running Compose
daemon, then call your endpoint:

```bash
iii trigger -n dev compose::add worker=http
```

```bash
curl -X POST http://localhost:3111/hello \
  -H "Content-Type: application/json" \
  -d '{"name": "iii"}'
```

Expected response:

```json
{ "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:

```bash
iii trigger -n dev compose::add worker=state
iii trigger -n dev compose::add worker=queue
iii trigger -n dev compose::add [email protected]
```

`compose::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:

```bash
npx skills add iii-hq/iii/skills
```

Skills teach your agent the top-level iii model: functions, triggers, workers, observers, 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` + `registerTrigger`
  calls
- Use `::` separator for function IDs to namespace them: `orders::create`, `orders::validate`
- Add cron trig

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

pip install iii-sdk iii-helpers
npx skills add iii-hq/iii/skills

git clone https://github.com/iii-hq/iii
git -C iii checkout 872770b7cf06

Works in

1. 2026-10-29
   ✓SAFE B 89 / 100

   first audit · source 872770b7cf06

Questions about iii-getting-started

• github.com/iii-hq/iii/tree/main/skills/iii-getting-started — the audited source at commit 872770b7cf06 and every finding aboveObserved · 29 Oct 2026

Spotted something wrong? Report a correction · Methodology