Loa/Arbor
English
  • English
  • 简体中文
  • 日本語
  • Español

Getting started: from nothing to an agent answering in your terminal

From docs/getting-started.md at Loa Arbor v0.2.6, as released.

Coming soon: the Homebrew tap and Arbor's source aren't public yet, so the install steps below won't work for you today.

Shipped in the arbor binary (arbor docs get docs/getting-started.md). Steps 1 to 9 were run on 2026-11-22 against arbor 0.2.4 installed from the tap, on macOS (Apple silicon) with a local model; where a step’s output is shown, it is that run’s, trimmed.

Arbor runs your app on a node: a process that keeps every actor’s inbox, ledger and state, and advances them one committed step at a time. You write the app in TypeScript; Arbor builds it, type-checks it, and runs it. In nine steps you install Arbor, run an app on a node of your own, turn it into an agent on a model, and let a customer and a staff member talk to it.

1. Install Arbor

brew tap loaapp/tap && brew trust loaapp/tap && brew install arbor
arbor --version

The tap builds for macOS on Apple silicon and for Linux on x86-64 and ARM64. It installs TypeScript beside Arbor, so every build is type-checked. To build from the source instead, see “Installing from the source” at the end of this page.

2. Create a project

arbor init --name hello
cd hello

init writes a project that runs as it is:

  • app.ts, the app: one plain actor that answers every message with “hello: “.
  • arbor.yaml, the project: its name, the environments it deploys to, the defaults every deploy carries, and the local node’s dev: block.
  • AGENTS.md, for a coding agent working in the project.
  • package.json, prompts/ and .gitignore.

3. Run it on a local node

arbor dev watch
local node: http://127.0.0.1:8787 (data in ~/.arbor/projects/hello)
type check: on (tsc 7.0.2)
Building: hello@0.1.0-dev.1 (ab601930…) - OK, 50ms
Deploying to local:
- revision 1 - OK
- latest -> 1
App: http://127.0.0.1:8787/ui/apps/hello
Watching for changes...

dev watch starts a node of the project’s own: SQLite under ~/.arbor/projects/hello, listening on loopback only. It builds the app, publishes it, and does both again on every save. Leave it running and use a second terminal for the steps below.

  • type check: on means your builds are type-checked. If it says off, it names the command that installs TypeScript for the way you installed Arbor. A build that cannot be type-checked is still published, and says so.
  • The .npmrc warning on the first run matters only when another project installs this app’s packages from the node; arbor npm setup writes that file.
  • Another port: set dev.port in arbor.yaml, or ARBOR_DEV_PORT=8790 arbor dev watch.

4. Talk to it

S=$(arbor session open)
arbor session send --session "$S" "hi there"
arbor session follow --session "$S" --until reply --for 60s
2 [session] participant_joined: {"participant":"p1","role":"user",…}
5 [-> greeter] user_msg: hi there
8 [greeter] reply: hello: hi there

A session is one conversation. open prints its id alone, so the shell can keep it. send posts a message as you, and follow prints what the session says. With --until reply it stops at the reply to your message, or after --for at the latest; without it, press Ctrl-C.

5. Make it an agent

An agent is an actor whose function is the model loop. Replace app.ts with:

import { agent, bundle } from '@arbor/sdk';

const desk = agent('desk', {
  instructions: 'You answer questions for a small bookshop. Answer briefly and plainly.',
}).wake('chat');

export default bundle({ app: 'hello', roots: [desk], session: { exposed: [desk] } });

Then tell the local node which model to call, in arbor.yaml’s dev: block. This run used a local Ollama model:

dev:
  model:
    name: gemma4:12b
    api: chat                       # responses | chat | anthropic
    base_url: http://localhost:11434/v1
  • Restart dev watch after changing dev:. It reads the block when it starts. A change to app.ts needs no restart.
  • With no model set, a node calls qwen3.8:27b through the Responses API at http://localhost:11434/v1, which is Ollama’s default address. A flag or an ARBOR_MODEL variable overrides the block.
  • A hosted model’s key goes in .env, as ARBOR_MODEL_API_KEY or ARBOR_MODEL_HEADERS, never in arbor.yaml. init’s .gitignore already leaves .env out of git.

Ask it something:

S=$(arbor session open)
arbor session send --session "$S" "Do you sell second-hand books?"
arbor session follow --session "$S" --until reply --for 60s
26 [desk] reply: Yes, we have a selection of pre-loved books. What are you looking for?

arbor session activity --session "$S" tells you what happened, in words: what woke the desk, the model call, its tokens and time, and the reply.

6. Give the model a role

A bundle never names a vendor’s model. It names a role, and the node’s settings map the role to a model, so the same release runs on one model in development and another in production. The role must be declared in the bundle:

const desk = agent('desk', { instructions: '…', model: 'fast' }).wake('chat');

export default bundle({
  app: 'hello', roots: [desk],
  models: { fast: { description: 'quick, cheap replies' } },
  session: { exposed: [desk] },
});

An agent that names an undeclared role fails the build. A declared role that nothing maps still publishes, with the warning model role "fast" is not mapped in the configuration (model.fast); its agents run on the node's base model. arbor revision get r3 shows the warning on the revision dev watch named (- revision 3 - OK). Map the role on the node, review the change, then publish it:

arbor settings set model.fast.model=gemma4:12b model.fast.api=chat model.fast.base_url=http://localhost:11434/v1
arbor draft review
arbor draft publish

settings set only stages a change into the app’s draft. draft publish makes it a revision, and new sessions run on it. A role can also name fallbacks, up to four models tried in order when the first fails, and another role as its default. Both are in docs/scripting.md (“Model roles”).

7. Let people join

A session’s people are its participants, each holding a role the app declares. Declare the roles in the bundle and name the ones the agent takes posts from:

const desk = agent('desk', { instructions: '…', model: 'fast' })
  .wake('chat')
  .participants(['customer', 'staff']);

export default bundle({
  app: 'hello', roots: [desk],
  models: { fast: { description: 'quick, cheap replies' } },
  session: {
    roles: {
      customer: { max: 1, principal: true },
      staff: { max: 2, join: 'invite' },
    },
    exposed: [desk],
  },
});

The bundle grants nothing by itself. The settings say who may hold each role, by audience, in arbor.yaml’s defaults::

defaults:
  role:
    customer: [employee, customer]
    staff: [employee]

On your local node you are the operator, with the audience employee, so you open sessions as the customer. Staff join only by invitation:

S=$(arbor session open)
arbor session send --session "$S" "Do you have the new Le Guin biography?"
arbor session join --session "$S" --role staff --subject sam --audience employee
arbor session follow --session "$S" --until reply --for 60s

To act as Sam, for example to approve a call that waits for staff, use his own token: TOKEN=$(arbor dev token --subject sam --audience employee), then pass --token "$TOKEN" to each command. docs/agent.md (“Held calls”) shows how.

8. Look at it in the console

Open the App: address that dev watch printed, http://127.0.0.1:8787/ui/apps/hello. The console shows the app’s sessions. Each session has its Chat, its Activity (what each actor did, in words), its Ledger (every committed step) and its Topology. On your local node it needs no sign-in.

9. Read the documents from the shell

The documents ship in the binary, so they match the arbor you have:

arbor docs search "model roles"
arbor docs get docs/scripting.md    # writing an app: agents, actors, tools, hooks, modules
arbor docs get docs/agent.md        # the CLI as a coding agent uses it

Next

  • Tools, held calls and approvals: docs/scripting.md (“Script tools”, and “Held calls: approval, client tools, external work”) and docs/held-calls.md.
  • Deploying to another node: arbor env set --name test --host https://…, then arbor env login --env test --code <invite> with an invite from that node’s operator, and arbor deploy --env test (docs/agent.md, “Environments”).
  • What Arbor is underneath: docs/core-model.md.

Installing from the source

git clone https://github.com/loaapp/arbor.git && cd arbor
make build                  # the console, the client and the binary: bin/arbor
pnpm -C sdk install         # TypeScript for the type check
./bin/arbor --version

make build needs Go, Node and pnpm. pnpm -C sdk install puts tsc where a node run from the checkout finds it. Without it, dev watch says type check: off and names that command. Put bin/ on your PATH, or call ./bin/arbor, and carry on from step 2.