Create your workspace

A workspace is the folder that holds everything you build: your agents, your workflows, and the packages they need. This page takes you from an empty folder to a running workspace with a model behind it.

Create it

From the folder that should hold the workspace:

Create the workspace

stackbone init my-workspace

The command asks what to start with. Pick Agent, so the workspace has something to run from the first minute:

◆◆◆ stackbone v0.3.3 · init

◇ Scaffolding workspace "my-workspace" (--with agent)
◇ Installing Stackbone agent skills for every detected coding agent…
◇ Dependencies installed with pnpm
◆ Workspace my-workspace ready

Next steps
  cd my-workspace
  stackbone dev

  The first run stops for setup: it prints a Studio
  link to point this deployment at a model provider.

Your coding agent
  Open your coding agent in the workspace and paste:

  Use the stackbone-coder skill. The "my-workspace" agent is already
  scaffolded in this workspace, so skip the scaffolding: interview me
  about what it should do, then wire it up.

You now have a folder with deep-agents/ for your agents, workflows/ for your workflows, and a package.json with its packages already installed (init runs pnpm install, or npm install when pnpm is not on your machine). The command also registers the workspace with your organization, so the dashboard knows about it before you run anything.

If the install failed, or you passed --no-install, the Next steps note keeps the install line for you to run yourself.

Start it

cd my-workspace
stackbone dev

This one command is the whole local loop. It starts a small Postgres, Redis and file store on Docker, opens a tunnel so the dashboard can reach your laptop, and prints where everything lives:

◆◆◆ stackbone v0.3.3 · dev

◇ Docker services ready (postgres + minio ready)
◇ Platform migrations applied (46 applied, 0 skipped)
◇ Agent migrations applied
◇ Tunnel ready (https://a1b2-c3d4e5f6.tun.stackbone.ai)

  ▸ Open Studio  https://app.stackbone.ai/app/acme/installations/019e92f9…?stackbone-dev=…

    Tunnel       https://a1b2-c3d4e5f6.tun.stackbone.ai
    Local        http://127.0.0.1:4242

    Agent        my-workspace
    Protocol     v15 · 10 capabilities

The Open Studio link is the one to keep. It carries the tunnel address at the end (?stackbone-dev=…), which is how the dashboard reaches the workspace on your laptop rather than a server.

Leave the terminal running. Everything below assumes it stays open.

Note

stackbone init also asks which coding agents you use. Whatever you tick gets the Stackbone agent skills and this documentation as an MCP server, so your coding agent knows the commands and the SDK without you explaining them.

Connect a model provider

The first run stops before it starts your code, and says why:

▲ Your workflows and agents are not running yet.

  This deployment has no model provider configured, so agents that name a
  model cannot start.

  Configure one in Studio:
  https://app.stackbone.ai/app/acme/installations/019e92f9…/studio/first-run?stackbone-dev=…

  Prefer the terminal? Export MODEL_PROVIDER_BASE_URL (and MODEL_PROVIDER_API_KEY,
  if your provider needs a key) and run `stackbone dev` again.

This is expected. Your agents name a model, and no model can be reached yet, so Stackbone holds your code back instead of letting every agent fail one by one. A model provider is the address Stackbone sends model calls to. Any OpenAI-compatible endpoint works: OpenRouter, a local Ollama or LM Studio, or a gateway of your own.

Open the link the CLI printed. It lands you on a three-step setup in Studio, the dashboard for your running workspace.

The rest of this section follows the browser. To stay in the terminal, export MODEL_PROVIDER_BASE_URL (and MODEL_PROVIDER_API_KEY, if your provider needs a key) and run stackbone dev again. The gate opens on the first start that finds them.

Name the endpoint

Pick a preset to fill in the base URL, or choose Custom and type your own. The key is optional, because a gateway running on your own machine does not ask for one:

Preset Base URL API key

OpenRouter https://openrouter.ai/api/v1 Yes

Ollama http://localhost:11434/v1 No

LM Studio http://localhost:1234/v1 No

Custom You type it Ask your gateway

Choosing OpenRouter fills the base URL for you.

Click Test connection. Stackbone calls the endpoint before it saves anything. A wrong key or a typo in the URL comes back here as the provider's own error message, instead of turning up later as a broken agent.
Pick the default model

A working connection gives you the list of models that endpoint serves. Do two things with it.

Check that the model your agent asks for is on the list. Agents name their own model in their own code, and the scaffolded one asks for openai/gpt-4o-mini.

Then click a model to make it this workspace's default, the one Stackbone's own built-in workflows use. Entries that cannot hold a conversation, such as image or embedding models, stay visible but cannot be picked.

The models the endpoint serves. The picked one is marked default.
Save and start

Click Save and start. The key is encrypted into your workspace's own store, your agents start, and Studio reports how many came up:

Your agent is running. Nothing needed a restart.

Preset	Base URL	API key
OpenRouter	`https://openrouter.ai/api/v1`	Yes
Ollama	`http://localhost:11434/v1`	No
LM Studio	`http://localhost:1234/v1`	No
Custom	You type it	Ask your gateway

Back in the terminal, stackbone dev carries on by itself, with no restart and no second command to run.

Note

No provider to hand? Choose Continue without a provider. Your workspace starts, the dashboard works, and your agents show up in the catalog. They cannot answer until you come back and fill this in.

Change it later

Everything you chose lives on the Model provider screen, under Settings in the left menu. Point the workspace at a different endpoint, replace the key, or click Run the guided setup again to walk the three steps a second time:

A change here takes effect straight away.

Saving with an empty key clears the stored one, which is what you want when you move from a hosted provider to a local gateway.

If something goes wrong

What you see	What to do
`Unauthorized` from `stackbone init`	The workspace is registered with your organization, so sign in first with `stackbone login`.
`stackbone dev` stops on the Docker step	Docker is not running. Start it, then run `stackbone dev` again.
Test connection returns the provider's own error	The endpoint answered and refused. Check the key first, then the base URL.
The setup screen sends you to Model provider instead	Somebody already ran the setup here. Use Run the guided setup again to walk it a second time.
The catalog says an entry is waiting for a provider	The agent is registered but has no model to call. Finish the setup and it starts.

What's next

Add your first agent: an agent you start and chat with.
Add your first workflow: a job that runs in steps and finishes on its own.