Getting started

From zero to a running agent on your laptop in 5 minutes.

From zero to a running agent on your laptop in 5 minutes. No marketplace publish, no cloud deploy — just the local emulator and a Hono /invoke handler.

Prerequisites

Node.js ≥ 24 LTS. The CLI binary and every official template target Node 24. Earlier versions are not supported.
Docker. stackbone dev boots Postgres + MinIO via docker compose.
A Stackbone account. Sign up at app.stackbone.com. The CLI authenticates via the magic-link -code flow .

OS support: the CLI is tested on macOS, Linux and Windows (PowerShell

WSL). Windows users get the same binary; the stackbone dev emulator uses Docker Desktop or Docker Engine on WSL2.

1. Install

The CLI is published as @stackbone/cli and runs through npx without installing anything globally:

npx stackbone --help

If you prefer a global install:

pnpm add -g @stackbone/cli   # or: npm i -g @stackbone/cli
stackbone --help

You can also pin the CLI per project — stackbone init already adds @stackbone/cli to the generated package.json so pnpm stackbone ... works inside the project.

2. Authenticate

stackbone login

This opens the device-code flow (RFC 8628):

A short verification code is printed to the terminal.
Your browser opens to the verification URL.
After confirming the magic link from your inbox the CLI stores a session in ~/.stackbone/credentials.json (chmod 600).

Headless / CI? Pass --no-browser and follow the printed URL manually (also auto-detected when CI, SSH_CLIENT, or SSH_TTY is set):

stackbone login --no-browser

Verify with:

stackbone whoami
# user:      jane@acme.com
# user id:   ...
# workspace: Acme (acme)
# endpoint:  https://api.stackbone.dev

3. Scaffold an agent

Pick a directory name (it doubles as the agent slug) and a template:

stackbone init my-first-agent --template hello-world
cd my-first-agent
pnpm install

stackbone init does six things in one shot:

Calls the control plane to create an agent record (name, slug, description).
Writes the template files under the target directory.
Writes agent.yaml (the manifest).
Writes .stackbone/project.json (workspace + agent + control-plane URL).
Patches .gitignore.
Writes .claude/skills/stackbone/SKILL.md so Claude Code (and any other coding agent that reads .claude/skills/) knows how to use the CLI.

See Claude Code skill for what the skill contains.

4. Run the local emulator

stackbone dev

This boots:

The agent process under node --watch src/index.ts (port auto-picked).
A local Postgres + MinIO stack via docker compose.
The Studio API at http://127.0.0.1:4242.
A Cloudflare quick tunnel so the cloud-hosted Stackbone Studio (app.stackbone.com/studio) can reach the emulator without mixed-content issues. Pass --no-tunnel to skip it.

The boot banner prints both URLs:

┌─ stackbone dev ───────────────────────────────────────────────┐
│  Studio (cloud, recommended): https://app.stackbone.com/studio?baseUrl=...
│  Studio (local fallback):     http://127.0.0.1:4242
└────────────────────────────────────────────────────────────┘

5. Invoke the agent

The agent serves the Stackbone Agent Protocol. The minimal contract is POST /invoke, GET /health, GET /schema:

curl -X POST http://127.0.0.1:<agentPort>/invoke \
  -H 'content-type: application/json' \
  -d '{"who":"world"}'
# → {"hello":"world"}

The agent port is printed in the stackbone dev boot output and is also exposed on the Studio API.

What's next

Read Agent protocol to understand the full HTTP surface (input/output schemas, errors, SSE).
Read @stackbone/sdk integration when you're ready to talk to the database, storage, an LLM, RAG or HITL.
Push to the cloud: Deploying to Fly Machines — TODO.

Stuck? Run stackbone docs cli for the inline reference (no network) or open Troubleshooting — TODO.