---
title: 'Create your workspace'
description: 'Build the folder that holds your agents, start it, and point it at a model from the dashboard.'
position: 3
---
# 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:
1. **Create the workspace**
```sh
stackbone init my-workspace
```
The command asks what to start with. Pick **Agent**, so the workspace has
something to run from the first minute:
```text
◆◆◆ 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.
2. **Start it**
```sh
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:
```text
◆◆◆ 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](/docs/home/get-started/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:
```text
▲ 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.
1. **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.
2. **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`._
3. **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._
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](/docs/home/get-started/first-agent)**: an agent you
start and chat with.
- **[Add your first workflow](/docs/home/get-started/first-workflow)**: a job
that runs in steps and finishes on its own.