---
title: 'Welcome to Stackbone'
description: 'Your first hour with Stackbone: install the CLI, build one agent, and talk to it on your own laptop.'
position: 1
---

# Welcome to Stackbone

Stackbone is a platform for building AI agents and workflows in TypeScript and
running them in a container you own. The CLI scaffolds the workspace. The SDK
gives your code a database, file storage, models and third-party connectors,
already wired. **Stackbone Studio** is the dashboard where you chat with what you
built, watch every run, approve what needs a person, and connect tools such as
Gmail or Slack.

<details class="wiki-panel">
<summary>Give your coding agent these docs.</summary>

`https://docs.stackbone.ai/mcp` serves this whole site over the Model Context
Protocol. Your agent searches it and reads any page on its own, so it answers
from the current docs instead of guessing. It is public: no key, nothing to
install.

In Claude Code:

```bash
claude mcp add --transport http stackbone-docs https://docs.stackbone.ai/mcp
```

In any client that takes a JSON config (Cursor, Windsurf, Cline, Codex):

```json
{
  "mcpServers": {
    "stackbone-docs": {
      "type": "http",
      "url": "https://docs.stackbone.ai/mcp"
    }
  }
}
```

[More ways to hand over the docs](/docs/home/get-started/coding-agents#give-your-agent-these-docs),
including plain text files for an agent with no MCP support.

</details>

![The Stackbone Studio Playground, chatting with an agent that replies in the browser.](/images/first-steps/playground-chat.png)
_The Playground, where you chat with the agent you just built._

<details class="wiki-prompt">
<summary>Start faster with your coding agent.</summary>

```text
Set up a new Stackbone workspace. Stackbone runs durable AI agents and
workflows on a modern TypeScript stack. Before you run any command, ask these
questions one at a time and wait for each answer, unless it was already given:

1. Workspace name? (default: "my-workspace")
2. What should the workspace start with? (required; one of: "agent",
   "workflow", "workflow-agent", "empty"). If the answer is not one of those
   four, ask again and list them.

There is no offline setup, so check the session first with `stackbone whoami`
and run `stackbone login` if it fails. Login prints a short code and confirms
it in the browser. There are no passwords.

Then run, from the folder that will hold the workspace:

  stackbone init <workspace-name> --with <choice>
  cd <workspace-name>

`stackbone init` scaffolds the workspace, registers it with the user's
organization, sets up the Stackbone agent skills for the coding agents the
user picks (pass `--agents claude-code,cursor,...` when there is no terminal
to answer the prompt), and installs the dependencies (`pnpm install`, or
`npm install` when pnpm is missing). With "empty" it writes only the shell, so
add the first piece afterwards with `stackbone add agent <name>` or
`stackbone add workflow <name>`.

Start the local runtime and leave it running in its own terminal:

  stackbone dev

It starts the agent and a small local database, then prints an "Open Studio"
link. Studio is the browser dashboard for the running workspace: the Catalog
lists what the workspace serves and the Playground is where you chat with an
agent.

A fresh workspace has no model provider yet, so the first start pauses and
prints a link to configure one (OpenRouter, OpenAI, and others) in Studio. The
running terminal picks up the choice on its own, with no restart. Tell the
user this is a one-time step.

Also point them at the four Stackbone agent skills, which teach a coding agent
the whole surface: https://docs.stackbone.ai/docs/home/get-started/coding-agents
```

</details>

## What you'll do

Follow the pages in order:

1. **[Install the CLI](/docs/home/get-started/install)**: get the `stackbone`
   command on your machine and sign in.
2. **[Create your workspace](/docs/home/get-started/first-workspace)**: one
   command builds the folder that holds everything you make.
3. **[Add your first agent](/docs/home/get-started/first-agent)**: put an agent
   in it, start it, and chat with it.
4. **[Add your first workflow](/docs/home/get-started/first-workflow)**: add a job
   that runs in steps and finishes on its own.
5. **[What's next](/docs/home/get-started/coding-agents)**: where to go once it works.

## What Stackbone gives you

Stackbone has two building blocks. [**Agents**](/docs/home/features/agents) are
for conversation: you send a message, the agent replies, and it keeps the thread
so you can keep talking. [**Workflows**](/docs/home/features/workflows) are for
jobs: a list of steps that finishes even if the process restarts halfway
through. If you are not sure which one you need, read
[Agent or workflow?](/docs/faqs/building/agent-or-workflow).

Both reach the same platform through one client, `stackbone`. Your code calls
`stackbone.database`, `stackbone.storage`, `stackbone.ai` and so on; the
runtime has already wired each one, so you build no clients and hold no
credentials in code. Everything below works the same on your laptop under
`stackbone dev` and in the container you deploy.

### Build with

| Feature                                          | What it gives you                                                                                                                                                                                               |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Agents](/docs/home/features/agents)             | Multi-turn agents you write as one file: a model, a system prompt and the tools it may call. The runtime serves them over the OpenAI, Anthropic and AG-UI chat APIs, so any compatible client can talk to them. |
| [Workflows](/docs/home/features/workflows)       | Durable functions that run in steps. Each step runs once, saves its result and retries on failure, so a run survives crashes and redeploys and can wait for days.                                               |
| [Database](/docs/home/features/database)         | A Postgres of the agent's own, reached through a typed Drizzle handle. You own the tables and the migrations; the connection string never appears in your code.                                                 |
| [Retrieval](/docs/sdk/data/rag)                  | Parse, chunk, embed, store and search documents on top of that same database, so an agent answers from your content.                                                                                            |
| [Storage](/docs/home/features/storage)           | S3-compatible object storage for the files an agent reads and writes, with per-agent prefixes and signed URLs.                                                                                                  |
| [Integrations](/docs/home/features/integrations) | Stackbone Connect: an operator connects a provider once in Studio, your code calls it by name, and a broker mints a short-lived token per call. Connectors also fire inbound: an email arrives, a run starts.   |
| [Gateway](/docs/home/features/gateway)           | One model client, `stackbone.ai`, for chat, embeddings and images. The operator picks who answers: OpenRouter, or any OpenAI-compatible endpoint.                                                               |
| [API](/docs/home/features/api)                   | The HTTP surface a running workspace exposes: chat, the model catalogue, workflow runs and health. The runtime owns it; you write no server.                                                                    |
| [Memory](/docs/home/features/memory)             | Long-term memory across sessions. The surface is typed on the client today but not live yet, so read the page before you build on it.                                                                           |

### Keep people in control

| Feature                                      | What it gives you                                                                                                                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Guardrails](/docs/home/features/guardrails) | Rules an operator sets once in Studio and the runtime enforces on every chat turn and workflow run: block, mask or hold for a person. It takes no code on your side.    |
| [Governance](/docs/home/features/governance) | Studio, the dashboard for a running box: follow every run, decide what waits for a person, set the rules the runtime enforces, and measure a change before you ship it. |
| [Evaluation](/docs/home/features/evaluation) | Score an agent against saved cases from Studio or from CI, and fail the build when a change makes it worse.                                                             |

### Run and operate

| Feature                                                | What it gives you                                                                                                            |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| [Observability](/docs/home/features/observability)     | The logs your tools and steps emit, and a run timeline the platform records for every agent turn and workflow run.           |
| [Recurring jobs](/docs/home/features/recurring-jobs)   | Work on a schedule, as a fresh workflow run per tick, so it shows up in the runs list like any other run.                    |
| [Security and auth](/docs/home/features/security-auth) | Callers prove who they are against the workspace over HTTP. Secrets sit encrypted outside your code and reach it at runtime. |
| [Artifacts](/docs/home/features/artifacts)             | The files a run produces, kept in storage and handed out with a signed URL after the run has ended.                          |
| [Deploy](/docs/home/deployments/connect-your-box)      | You run the container in your own cloud and register it from the browser. Stackbone provisions nothing.                      |

## What you can do with Stackbone

Some of what you can build, each with a worked example you can copy:

- [A support agent that answers from your own documents](/docs/examples/agents/retrieval-backed)
  and looks an order up in its database.
- [An agent whose tone an operator changes from the dashboard](/docs/examples/agents/config-driven),
  with no redeploy.
- [A refund that waits for a manager](/docs/examples/workflows/refund-approval)
  and pays out only on a yes.
- [A morning digest that starts itself from a schedule](/docs/examples/workflows/scheduled-digest)
  and paces its own sends.
- [A signup pipeline that survives a restart](/docs/examples/workflows/onboarding-pipeline)
  halfway through validating, drafting and storing.
- [An agent that kicks off a background job](/docs/examples/workflow-agents/agent-starts-workflow),
  or [a job that asks an agent for a decision](/docs/examples/workflow-agents/delegate-to-agent).
- [An email an agent drafts and a person signs off](/docs/examples/workflow-agents/draft-then-approve)
  before it goes out.
- [An agent that opens a real browser](/docs/sdk/agents/browser-tools), logs in
  and pulls data off a page.

The smallest one, [a plain greeter](/docs/examples/agents/plain-greeter), is
where the Examples area starts.

## What's next

- **[Install the CLI](/docs/home/get-started/install)**: the first step.