---
title: Quickstart
description: Run Studio locally or deploy to your infrastructure
icon: Rocket
---

import Callout from "../../../../../components/ui/Callout.astro";

## 1) Run deco Studio

Pick the tier that fits. Studio hard-needs **PostgreSQL** and an
**S3-compatible object store**; **NATS** is bundled by the chart; the **sandbox**
(code-execution + previews) is an optional layer. The repo's [`selfhost/`](https://github.com/decocms/studio/tree/main/selfhost)
folder has ready-made scripts, example values, and the full dependency map.

| Tier | How | Dependencies |
|------|-----|--------------|
| **Local — CLI** | `bunx decocms` | embedded, on your machine |
| **Local — Compose** | `docker compose -f deploy/docker-compose/docker-compose.postgres.yml up` | all bundled (Postgres + NATS + MinIO) |
| **Local — Kubernetes** | one `helm install` of the umbrella `selfhost/examples/k8s-local` | all bundled (dev Postgres + MinIO + NATS + sandbox) |
| **Production — Kubernetes** | `helm install` [the chart](/en/studio/self-hosting/deploy/kubernetes) | external/managed Postgres + S3 + NATS + ClickHouse |

<Callout type="tip">
  **Prefer a guided install?** Add the interactive **self-host skill** to Claude Code — it walks you through the tiers below, asking what you have (dependencies managed or in-cluster, secrets, sandbox), filling the Helm values, validating with `helm template`, and installing.
</Callout>

Add it once (the repo is public), then tell Claude Code **"install Studio"**:

```bash
curl -fsSL https://raw.githubusercontent.com/decocms/studio/main/selfhost/skills/install.sh | sh
```

### Option A: one-command local (CLI)

```bash
bunx decocms
```

Local instance with an embedded PostgreSQL — fully private. The package is
published as `decocms`; the binary it ships is `deco`.

### Option B: Docker Compose (bundled everything)

Runs Studio + PostgreSQL + NATS + MinIO as containers, all wired — no external
services needed. Multi-arch images (runs native on Apple Silicon).

```bash
git clone https://github.com/decocms/studio.git
cd studio
docker compose -f deploy/docker-compose/docker-compose.postgres.yml up
open http://localhost:3000     # sign up — first user becomes org owner
```

Override the dev defaults (secrets, credentials) via a `.env` next to the compose
file. **More details:** [Local: Docker Compose](/en/studio/self-hosting/deploy/docker-compose)

### Option C: run from source

```bash
git clone https://github.com/decocms/studio.git
cd studio
bun install
bun run dev
```

### Option D: Kubernetes

The official chart (`deploy/helm/studio`) is **lean**: it deploys Studio + NATS
and expects **external** PostgreSQL, object storage (S3), and (optionally)
ClickHouse.

For a **local cluster** (Rancher Desktop / kind / minikube), an umbrella chart
(`selfhost/examples/k8s-local`) composes the lean chart + sandbox layer as Helm
dependencies and adds throwaway Postgres + MinIO — so one `helm install` brings
up the whole stack, wired, including the sandbox:

```bash
helm dependency build selfhost/examples/k8s-local
helm install deco-studio selfhost/examples/k8s-local -n deco-studio --create-namespace
kubectl -n deco-studio port-forward svc/deco-studio 8080:80   # → http://localhost:8080 (reliable on any cluster)
# studio.localhost also works IF the LoadBalancer claimed :80 — on stock Rancher Desktop k3s Traefik owns :80, so use the port-forward
```

Use the release name `deco-studio`. `./selfhost/scripts/local-k8s.sh` wraps this
(plus rollout wait and `uninstall`).

For **production**, point the chart at managed services and use external secrets
+ autoscaling. See [Kubernetes: Helm Chart](/en/studio/self-hosting/deploy/kubernetes).

<Callout type="tip">
  The full picture — tiers, the batteries-included vs. swappable-dependency model,
  the sandbox (egress lockdown + previews), local Kubernetes runtimes, and the
  production posture — lives in [`selfhost/README.md`](https://github.com/decocms/studio/tree/main/selfhost).
</Callout>

## 2) Create a Connection

When you open a new organization, deco Studio will prompt you to:

- **Browse Store** or
- **Create Connection** directly - provide the MCP URL (HTTP endpoint) and any required credentials

The **Store** is a catalog of Connections you can connect to. By default, the Store points to the **official MCP Registry**.

## 3) Create an organization and invite members

- Go to **Members**
- Invite teammates
- Assign roles (Admin/User) as needed

## 4) Create an Agent (virtual server)

- Go to **Agents**
- Click **Create Agent**
- Choose **Include** (only selected connections/tools) or **Exclude** (everything except the exclusions)

## 5) Generate an API key for a client

Create an API key with the minimum tool permissions needed (see [API Keys](/en/studio/api-keys)).

## 6) Verify monitoring

Use **Monitoring** to confirm:

- tool invocations are being logged
- latency + error rates show up
- filters (time range, tool name, connection, agent) work as expected

<Callout type="tip">
  The fastest smoke test is to call a tool through an agent endpoint (so you exercise aggregation + proxy + monitoring).
</Callout>


