Skip to main content
There are two ways to stamp an agent from a template: during installation, or anytime with ncl.

​
During installation

Run the installer and setup offers a template before it builds the sandbox:
At the prompt “How should we create your first agent?” you get three choices: 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.
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.
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 for what an update covers.

​
Presetting a template

Advanced setup exposes the pick as First-agent template, which resolves to a local ref. The same setting is available as a flag or an environment variable:
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

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.
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.
--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.
To point the library somewhere else, set NANOCLAW_TEMPLATES_DIR to another local path. It is never a URL and never changes at runtime.
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.

​
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:
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, reader notices come back under report instead.

​
After stamping

1

Wire it to a channel

Stamping creates the agent identity only. Connect it to a chat the usual way:
See Channels for the per-platform setup.
2

Connect credentials

Templates ship no secrets. Any MCP server that needs an API key gets one from the OneCLI Agent Vault, 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.
3

Activate recurring tasks

Template tasks are created paused, so stamping never starts background work without your consent. List and enable them:
Resuming follows normal scheduled task semantics — if the stored next run passed while the task was paused, it becomes eligible immediately.
4

Set the provider, if you want a specific one

The template doesn’t pick one. To override the install default:
See Providers.

​
What stamping actually created

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 instead.

​
Next steps

Updating a stamped agent

Pull a newer version of the template into an agent already running.

Building a template

Build your own and contribute it to the catalog.
Last modified on September 4, 2026