Quickstart

In this tutorial you will learn how iii makes it unreasonably simple to build and extend systems.

Make sure you have installed iii before proceeding. If you haven’t then visit the Install guide first. There you can also learn how to set up iii for agentic development.

The Quickstart is our original tutorial. If you want a guided, agentic learning experience that can be completed in a few minutes then run the install script and press “y” when prompted.

1. Create the project

iii project init quickstart --template quickstart
cd quickstart

This creates the two workers that you’ll run: a Python worker that adds two numbers and stores the sum in state, and a TypeScript worker that exposes an http endpoint and calls the Python worker through the iii engine.

workers/
  math-worker/
    src/math_worker.py  # Python worker
  caller-worker/
    src/worker.ts       # TypeScript worker

2. Start the engine

iii compose --up

Compose starts the engine and its daemon. The engine is now listening on ws://localhost:49134. Keep this terminal open. Run the remaining commands from a second terminal in the same directory. All commands in this tutorial use the default namespace.

3. Start the Python worker

Workers only need a WebSocket connection to the iii engine. They can run locally, in the cloud, replicated in kubernetes, or anywhere else.

iii trigger compose::add worker=./workers/math-worker

The Compose daemon terminal reports the worker becoming ready:

→ math-worker starting
✓ math-worker ready (2.1s)
up: 1 of 1 changed in 2.1s

Workers boot in a microVM that needs access to /dev/kvm. If the worker fails with KVM not accessible, see Troubleshooting.

This worker registered the function math::add with the engine. You could call this function right now using the command below.

iii trigger math::add a=2 b=3

However this is not much different than running an equivalent script on its own. The utility of iii comes from being able to place any functionality into a worker and then compose that worker with other workers through the engine, regardless of where each one runs or what language it’s written in.

Workers need a moment to install their runtime dependencies after being added. If you see "message": "Function math::add not found", wait a few seconds and try again.

4. Start the TypeScript worker

iii trigger compose::add worker=./workers/caller-worker

The Compose daemon reports:

→ caller-worker starting
✓ caller-worker ready (2.1s)
up: 2 of 2 changed in 2.1s

This worker registered the function math::add_two_numbers with the engine.

5. Call across languages

Call the TypeScript worker. It will call the Python worker through the engine and return the result:

iii trigger math::add_two_numbers a=10 b=20

{ "c": 30 }

6. Add state

compose::add incrementally adds workers from the registry to your running project. Add the state worker, which gives every function access to a persistent key-value store. From the folder containing worker-compose.yaml, run:

iii trigger compose::add worker=state

Now open workers/math-worker/src/math_worker.py in your code editor and uncomment the state block so the handler looks like this:

def add_handler(payload: dict) -> dict:
    a = payload.get("a", 0)
    b = payload.get("b", 0)
    logger.info(f"math::add called in Python with a={a}, b={b}")
    result = {"c": a + b}

    running_total = worker.trigger(
        {
            "function_id": "state::get",
            "payload": {"scope": "math", "key": "running_total"},
        }
    )
    new_total = (running_total or 0) + result["c"]
    worker.trigger(
        {
            "function_id": "state::set",
            "payload": {"scope": "math", "key": "running_total", "value": new_total},
        }
    )
    result["running_total"] = new_total

    return result

Save the file and call the function a few times:

iii trigger math::add a=2 b=3

{ "c": 5, "running_total": 5 }

iii trigger math::add a=10 b=20

{ "c": 30, "running_total": 35 }

The running total persists across every call, including calls that arrive through math::add_two_numbers.

7. Add HTTP endpoints

Now let’s add an HTTP worker to expose your functions as REST endpoints. From the folder containing worker-compose.yaml, run:

iii trigger compose::add worker=http

Open workers/caller-worker/src/worker.ts and uncomment the HTTP block at the bottom of the file:

worker.registerFunction(
  "http::add_two_numbers",
  async (payload: { body: { a: number; b: number } }) => {
    const result = await worker.trigger<
      { a: number; b: number },
      { c: number; running_total: number }
    >({
      function_id: "math::add_two_numbers",
      payload: payload.body,
    });
    return {
      status_code: 200,
      body: { c: result.c, running_total: result.running_total },
      headers: { "Content-Type": "application/json" },
    };
  },
);

worker.registerTrigger({
  type: "http",
  function_id: "http::add_two_numbers",
  config: { api_path: "/math/add-two-numbers", http_method: "POST" },
});

Save the file, then call the new endpoint with curl:

curl -X POST http://localhost:3111/math/add-two-numbers \
  -H 'Content-Type: application/json' \
  -d '{"a": 100, "b": 200}'

{ "c": 300, "running_total": 335 }

The same functions that respond to iii trigger now also respond to HTTP requests with no code changes to the handlers themselves.

How it works

For a walkthrough of how the engine, workers, functions, and triggers in this scaffold fit together, see Understanding iii. It uses this project as the worked example.

Open the iii Console with iii console in a new terminal: an interactive UI for workers, functions, triggers, logs, traces, and state. See the full Console documentation for details.

Next Steps

You scaffolded a project, started two workers in different languages, called functions across them, added persistent state, and exposed everything over HTTP, all by incrementally adding workers to a running system.

Real-world tutorial

Go beyond the basics and explore the full power of iii by building a real-world application.

Use iii

Learn how to use iii in production.

Understanding iii

Understand workers, triggers, and functions from a conceptual point of view.

Getting Started

Upgrading

Using iii

Understanding iii

Creating Workers

Quickstart

1. Create the project

2. Start the engine

3. Start the Python worker

4. Start the TypeScript worker

5. Call across languages

6. Add state

7. Add HTTP endpoints

How it works

Next Steps

Real-world tutorial

Use iii

Understanding iii

​1. Create the project

​2. Start the engine

​3. Start the Python worker

​4. Start the TypeScript worker

​5. Call across languages

​6. Add state

​7. Add HTTP endpoints

​How it works

​Next Steps

Real-world tutorial

Use iii

Understanding iii

1. Create the project

2. Start the engine

3. Start the Python worker

4. Start the TypeScript worker

5. Call across languages

6. Add state

7. Add HTTP endpoints

How it works

Next Steps