> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getasym.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# spin

> Create and start one or more clones from templates.

```bash theme={null}
asymmetric spin <template...> [options]
```

Creates and starts one or more clones. Allocates an id and ports, ensures shared
infra is up, creates and migrates the database, builds and starts the containers,
waits for health, and records the clone. See
[what spin does, end to end](/concepts/how-it-works#what-spin-does-end-to-end).

## Arguments

| Argument        | Required | Description                                               |
| --------------- | -------- | --------------------------------------------------------- |
| `<template...>` | yes      | One or more template names. Pass several to spin a fleet. |

The shipping templates are `slack`, `stripe`, `linear`, `github`, `notion`, and
`hubspot`. Run `asymmetric ls --templates` to see them and the modes each
supports.

## Options

| Option                 | Default               | Description                                                                                                     |
| ---------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `-m, --mode <mode>`    | template's first mode | Which service set to run. Every template ships an `api` mode; `slack` additionally ships `full` (API + web UI). |
| `-g, --group <name>`   | none                  | Add these clones to a named [environment](/concepts/environments) (creates it if new).                          |
| `-s, --seed <fixture>` | none                  | Seed with a named fixture immediately after create.                                                             |
| `--expose`             | off                   | Publish on all interfaces (`0.0.0.0`). Default is localhost-only (`127.0.0.1`).                                 |
| `--json`               | off                   | Output the created clones as JSON (suppresses the human summary cards).                                         |

## Examples

Spin one clone:

```bash theme={null}
asymmetric spin slack
```

```
  ✓ slack-a1b2  (api)  http://127.0.0.1:3001/api  ready in 38.2s
    db clone_slack_a1b2 · env -
    bot token   xoxb-…
    user token  xoxp-…
```

Templates that expose an apps/provision surface (today, `slack`) auto-provision a
default app on spin and print a bot + user token for programmatic access. Reprint
them later with [`asymmetric tokens <id>`](/cli/tokens). Templates without that
surface simply omit the token lines.

Spin with the full UI and a fixture, in one step:

```bash theme={null}
asymmetric spin slack --mode full --seed acme-corp
```

Spin several clones — even different templates — into one
[environment](/concepts/environments):

```bash theme={null}
asymmetric spin slack stripe --group workspace-1
```

```
  ✓ slack-a1b2  (api)  http://127.0.0.1:3001/api  ready in 38.2s
    db clone_slack_a1b2 · env workspace-1
  ✓ stripe-c3d4  (api)  http://127.0.0.1:3002/api  ready in 12.7s
    db clone_stripe_c3d4 · env workspace-1
```

Both clones become members of environment `workspace-1`; manage them as a unit
with [`asymmetric env`](/cli/environments).

Expose to other machines on your network (use with care):

```bash theme={null}
asymmetric spin slack --expose
```

## The summary card

Each clone prints two lines:

```
  ✓ <id>  (<mode>)  <endpoint>  ready in <n>s
    db <database> · env <environment>
```

The endpoint is the API URL if there is one, else the web URL, else
`(no endpoint)`. `<environment>` is the name passed with `-g`, or `-` if none.
When you pass `--seed`, a `seeded: <fixture>` line is printed below. For
templates that auto-provision an app, two more lines — `bot token` and
`user token` — carry the credentials for programmatic access (shown once here;
reprint with [`asymmetric tokens`](/cli/tokens)).

## Partial failure

Templates are spun independently. If one fails, the others still come up and the
failure is printed to stderr; the command exits `1`:

```
  ✓ slack-a1b2  (api)  http://127.0.0.1:3001/api  ready in 38.2s
    db clone_slack_a1b2 · env -
  ✗ figma: Unknown template "figma". List templates: asymmetric ls --templates
```

A clone that fails *mid-create* is rolled back automatically — containers and
volumes removed, database dropped — so you never get a half-built clone.

## Errors you might see

| Error                | Cause                                                                   |
| -------------------- | ----------------------------------------------------------------------- |
| `DOCKER_UNAVAILABLE` | Docker isn't running.                                                   |
| `TEMPLATE_NOT_FOUND` | No template with that name.                                             |
| `NO_FREE_PORTS`      | The port range is exhausted; destroy a clone or widen it.               |
| `HEALTH_TIMEOUT`     | The backend didn't become healthy in 90s. Check `asymmetric logs <id>`. |
| `CLONE_START_FAILED` | A create/migrate/compose step failed.                                   |

See the [full error reference](/reference/errors).