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

# Using a template

> Stamp an agent from a template during install or anytime with ncl, then wire it to a channel, connect credentials, and activate its recurring tasks.

There are two ways to stamp an agent from a [template](/templates/overview): during installation, or anytime with `ncl`.

## During installation

Run the installer and setup offers a template before it builds the sandbox:

```bash theme={null}
bash nanoclaw.sh
```

At the prompt **"How should we create your first agent?"** you get three choices:

| Choice | What it does |
| - | - |
| **Fresh agent** | The default. No template — shape the agent by chatting with it. |
| **From the NanoClaw template library** | Clones [`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates), lists what's in it, and copies your pick into your local `templates/` before stamping. |
| **From local templates** | Lists the templates already in your `templates/` directory. |

Setup then stamps the agent through the same `ncl groups create --template` command described below. The agent is created even when channel setup is skipped or can't finish wiring — when a channel is ready later, setup wires that existing agent and sends the welcome message.

The provider you pick during setup stays separate from the template.

<Note>
  Existing installs see **"Would you like to add or update an agent from a template?"**, with **No template changes** selected by default. You can also use the CLI below or pass an explicit template path.
</Note>

**If setup failed partway through**, the unfinished selection stays in `.env` for retry. When the template already has agents, setup offers to connect an unwired agent, update a selected agent in place, create another agent with a distinct name, or cancel. Updates preserve the provider and skip channel setup; declining the update cancels that operation. Completed create, connect, or update operations clear the saved selection. See [Updating a stamped agent](/templates/updating) for what an update covers.

### Presetting a template

Advanced setup exposes the pick as **Agent template**, which resolves to a local ref. The same setting is available as a flag or an environment variable:

```bash theme={null}
bash nanoclaw.sh --template-path <category>/<template>
NANOCLAW_TEMPLATE_PATH=<category>/<template> bash nanoclaw.sh
```

An explicit template path is honored even on an existing install. If the ref isn't found under your templates directory, setup warns and falls back to the picker.

## Anytime, with `ncl`

```bash theme={null}
ncl groups create --template <category>/<template> --name "My Agent"
```

This creates the agent group and stamps every surface the template carries. It does **not** wire the agent to a channel — run `/manage-channels` (or `ncl wirings create`) afterward, exactly as for a [hand-built group](/guides/first-agent).

<Note>
  With no existing carrier of the template, this creates an agent. If one agent already carries it, the command returns an update plan; if several do, select one with `--id`. Pass `--new` to create another agent. A template cannot be adopted onto an unrelated existing agent; updating a carrier of the same template is [restamping](/templates/updating).
</Note>

`--name` is optional. Without it the display name falls back to the template's own `agentName`, then to the template folder name. `--timezone <iana-id>` sets the group timezone, which is what template task schedules fire in.

### The template ref

`--template <ref>` is a path **relative to your local templates directory** — `templates/` by default, or `NANOCLAW_TEMPLATES_DIR`. Refs are multi-segment, so `<category>/<template>` resolves to `templates/<category>/<template>`. The plugin root is the leaf folder, and its manifest `name` is independent of the path.

The ref must stay inside the templates directory. Absolute paths, a leading `~`, and `../` escapes are all rejected.

```bash theme={null}
ncl groups create --template <category>/<template>   # templates/<category>/<template>
ncl groups create --template /etc/passwd        # rejected: absolute path
ncl groups create --template ../../secrets      # rejected: escapes the templates dir
```

To point the library somewhere else, set `NANOCLAW_TEMPLATES_DIR` to another **local** path. It is never a URL and never changes at runtime.

<Warning>
  `NANOCLAW_TEMPLATES_DIR` is read by the **host process**, once at startup. Setting it on an `ncl` invocation does nothing — `ncl` is a socket client, and the host resolved the path long before your command arrived. To change it, set it in the host service environment and restart the host.
</Warning>

### Reading the create response

If the reader skipped or ignored anything — a non-conforming skill, an unsupported MCP transport, an unknown manifest field — the create response carries a `templateReport` array listing each item by name:

```json theme={null}
{
  "id": "ag-3f2c8a91-7b4d-4e1a-9c02-5f8ab6d31e77",
  "name": "My Agent",
  "folder": "my-agent",
  "…": "…",
  "templateReport": [
    "mcp.json: server \"legacy\" skipped: unsupported transport \"sse\"",
    "plugin.json: unknown field \"icon\" ignored"
  ]
}
```

Components are never silently stripped. A missing `templateReport` means everything loaded. Fatal problems — an invalid manifest, a symlink, a smuggled credential — reject the whole template instead, and no group is created.

`templateReport` is specific to the create response. When the same command [updates an existing agent](/templates/updating), reader notices come back under `report` instead.

## After stamping

<Steps>
  <Step title="Wire it to a channel">
    Stamping creates the agent identity only. Connect it to a chat the usual way:

    ```bash theme={null}
    /manage-channels
    ```

    See [Channels](/channels/overview) for the per-platform setup.
  </Step>

  <Step title="Connect credentials">
    Templates ship **no secrets**. Any MCP server that needs an API key gets one from the [OneCLI Agent Vault](/operate/credentials), which injects it into outbound HTTPS calls at request time — matched by API host.

    The common path needs no setup up front: the first time the agent calls a service with no credential, the API returns `401`/`403` and the agent replies with a prefilled connect link for that host. Open it, paste the key, and ask the agent to retry.

    Check the template's own `README.md` for which services it expects, the scopes each key needs, and whether any of them is a **paid** service — registry templates must declare that up front, with a link to the tool and the tier they need. You always supply your own key.
  </Step>

  <Step title="Activate recurring tasks">
    Template tasks are created **paused**, so stamping never starts background work without your consent. List and enable them:

    ```bash theme={null}
    ncl tasks list --group <agent-group-id> --status paused
    ncl tasks resume <task-id>
    ```

    Resuming follows normal [scheduled task](/guides/scheduled-tasks) semantics — if the stored next run passed while the task was paused, it becomes eligible immediately.
  </Step>

  <Step title="Set the provider, if you want a specific one">
    The template doesn't pick one. To override the install default:

    ```bash theme={null}
    ncl groups config update --id <agent-group-id> --provider codex
    ncl groups restart --id <agent-group-id>
    ```

    See [Providers](/extend/providers).
  </Step>
</Steps>

## What stamping actually created

| Surface | Where it lands |
| - | - |
| The whole plugin | `groups/<folder>/plugins/<name>/`, mounted **read-only** in the container at `/workspace/agent/plugins/<name>` |
| Writable plugin state | `groups/<folder>/plugin-data/<name>/` |
| Persona | `groups/<folder>/instructions.prepend.md`, inlined at the top of the agent's `CLAUDE.md`/`AGENTS.md` every spawn |
| Extra context files | `groups/<folder>/`, keeping their layout relative to `instructions.md` |
| Skills | The group's private skills overlay — keyed to that group, never shared |
| MCP servers | The group's container config, marked plugin-owned |
| Tasks | Scheduled tasks in the DB, status `paused` |

Plugin-owned MCP servers are template content, so `ncl groups config add-mcp-server` and `remove-mcp-server` refuse to edit them. Change the template and [restamp](/templates/updating) instead.

## Next steps

<CardGroup cols={2}>
  <Card title="Updating a stamped agent" icon="rotate" href="/templates/updating">
    Pull a newer version of the template into an agent already running.
  </Card>

  <Card title="Building a template" icon="pen-ruler" href="/templates/building">
    Build your own and contribute it to the catalog.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.