NanoClaw Beyond the Basics: Groups, the ncl CLI, and Billing
Once NanoClaw is up and running on your Self-Managed VPS or Virtual Dedicated Server (VDS), the operations guide gets you to a working agent with one channel and one group. This article picks up from there — how to actually use the agent day to day, how to run more than one agent from the same install, how the ncl CLI and the approval workflow tie everything together, how to switch AI providers, and how to back up, migrate, or remove your install cleanly.
machinectl shell nanoclaw@ first if you're on a one-click VPS, or just your own shell in the project directory if you installed manually.1. Using the Agent Day to Day
There's no special syntax for talking to your agent — you message it in plain English on whichever channel you connected, the same way you'd message a person. It can run shell commands, read and write anything mounted into its container, browse the web, and use the CLI tools baked into the agent image (Claude Code itself, plus tools like vercel and a browser-automation skill).
How Conversations and Memory Carry Over
Two different things persist across sessions, and it helps to know which is which:
- Session history: each conversation session has its own inbound/outbound message queues, so the agent can pick a thread back up if you keep messaging in the same channel.
- Durable memory:
groups/<folder>/memory/is where the agent stores things it decides are worth remembering long-term — facts about you, ongoing projects, preferences — independent of any one conversation. You generally don't edit this by hand; the agent manages it itself as you talk to it.
If a conversation gets long and you want to free up context without losing what matters, ask the agent to compact it:
This summarizes the conversation so far and keeps the important parts, rather than just wiping the slate.
What It Can and Can't Do Out of the Box
Out of the box, your agent can chat, run commands inside its own container, and use whatever channels and skills you've installed. It can't see anything on your host filesystem unless you've explicitly allowed it through the mount allowlist, and it can't run destructive or account-level actions without triggering an approval — both covered later in this article.
2. Creating Additional Agent Groups
A single NanoClaw install isn't limited to one agent. Each group is its own isolated agent — its own instructions, its own memory, its own container — and you can run several from one VPS.
Creating a Group
Example Output:
messaging-group-id, not just a channel name — find one from a channel you've already connected:
By default this makes the agent only respond when @mentioned or DM'd. If you want it to respond to every message in that chat instead, add --engage-mode pattern --engage-pattern ".".
In our own testing, a successful wiring didn't automatically register a destination — pnpm ncl destinations list stayed unchanged. Confirm it after wiring, and add one by hand if it's missing:
Starting from a Template
If you're spinning up similar agents repeatedly, stamp them from a reusable template instead of configuring each one from scratch:
Templates bundle instructions, MCP tools, and skills — but never secrets — and load from your local templates/ folder. You can build your own or copy one in from NanoClaw's public template library.
3. The ncl CLI in Depth
ncl connects and modifies NanoClaw's central state — groups, messaging groups, wirings, destinations, users, roles, sessions, and pending approvals — from outside a chat conversation entirely. Every command in this section is written as pnpm ncl ..., since that's what works from a fresh checkout without any extra setup. If you've symlinked bin/ncl onto your PATH, you can drop the pnpm prefix and just run ncl ... directly — either form hits the same CLI.
Before You Trust Any Command in This Article — Check It Yourself
Every part of ncl is self-documenting, and it's worth leaning on that instead of memorizing flags from any guide, including this one:
What pnpm ncl help actually shows you: one line per resource, with a plain-English description and its list of verbs — e.g. wirings: list, get, create, update, delete. If a resource you need isn't listed, or a verb you were expecting isn't there, that's your install telling you directly rather than a guide telling you secondhand.
What pnpm ncl <resource> help adds on top: the exact flags that resource's create/update accept, which ones are required vs. optional, valid enum values, and defaults. This is the part worth checking before you run anything from this article — if a flag name here doesn't appear in your own pnpm ncl wirings help output, use what your install actually printed, not what's written here.
pnpm ncl <resource> help reflects your actual install, and this article can't. When the two disagree, trust the terminal.Read vs. Write, and Who's Allowed
Every ncl operation carries an access level, and the rule is the same across every resource:
- Reads are open —
list,get, andconfig getrun immediately for anyone with CLI access. - Mutations require approval — when called by an agent inside a container. Calling
nclyourself, from your own terminal, bypasses approval entirely — every command you run inline just executes.
That second point is what the approval workflow (next section) actually protects: not you, but what an agent can do on its own initiative.
pnpm ncl groups get abc123 works, but a real UUID (four hyphens) doesn't. Pass it as --id <uuid> instead.4. Switching or Mixing AI Providers
Claude is the default, but it's not the only option, and you're not locked into one provider for every group. Each group's provider is just a value in its container config, so you can run some agents on Claude, others on Codex or a local model, all from the same install.
Codex (ChatGPT / OpenAI)
Works with a ChatGPT subscription or an OpenAI API key. Credentials go through the OneCLI vault the same way Claude's do — never into a container directly.
OpenCode (OpenRouter, Google, DeepSeek, and more)
Ollama (fully local, open-weight models)
Useful if you want an agent that never calls out to a hosted API at all.
Assigning a Provider to a Specific Group
Example Output:
5. The Approval Workflow
This is the mechanism that keeps an agent from quietly taking sensitive actions on its own. When a containerized agent calls a mutation — installing a package, adding an MCP server, touching a credential — the command doesn't run. Instead:
- The call returns
approval-pendingto the agent, rather than executing. - An approval card is posted for an admin to review — in the same chat channel, or via the CLI.
- Once an admin approves or rejects it, the host executes (or discards) the action and notifies the agent of the outcome.
Resolved cards in shared channels get updated with who actually clicked Approve or Reject, so there's an audit trail even after the buttons themselves are gone.
Reviewing Pending Approvals
Each row shows the requesting session, the action being requested (e.g. install_packages, add_mcp_server), and how long it has before it expires unanswered.
Scoping What a Group's Agent Can Even Ask For
You don't have to leave every group able to request everything. Each group has a cli_scope that limits what its agent's ncl calls are allowed to touch in the first place:
6. Backups, Migration, and Uninstalling
What Actually Needs Backing Up
Almost everything that matters lives inside your project checkout — there's no external database or hosted state to worry about:
data/v2.db— the central database: agent groups, messaging groups, wirings, users, roles.data/v2-sessions/— per-session message history.groups/<folder>/memory/andinstructions.prepend.mdfor each agent..env— provider config and non-secret settings.~/.config/nanoclaw/(outside the project folder) — your mount and sender allowlists.
NanoClaw doesn't ship a one-command backup feature, so the straightforward approach is to stop the service and archive the project folder plus the config directory:
Store that archive somewhere off the VPS — it contains credentials and conversation history, so treat it with the same care as the server itself.
Migrating to a New VPS
To move an existing install to a new server, copy that same archive over, extract it in the same relative location, install NanoClaw's dependencies fresh (bash nanoclaw.sh will detect the existing data and offer to continue with it rather than starting over), and reconnect any channel that needs a fresh device pairing (WhatsApp's QR pairing, in particular, doesn't survive a server move automatically).
Uninstalling Cleanly
NanoClaw includes a built-in uninstaller that only removes what belongs to that specific checkout — it won't touch other NanoClaw installs on the same machine or your shared OneCLI credentials:
Review what it found, then run it for real:
It asks for confirmation per item before deleting anything, backs up your .env first, and removes the background service, containers and image, app data, logs, and this install's own OneCLI vault agents. The only manual step left afterward is deleting the checkout folder itself.
--yes instead of --dry-run to skip the confirmation prompts if you're automating a teardown — just make sure you've actually reviewed a dry run first.7. Cost and Usage Visibility
NanoClaw itself is free and open source — what you pay for is the AI usage behind it, billed directly by whichever provider a given group is using, plus the VPS itself. NanoClaw doesn't include its own billing dashboard or token-usage meter; there's no in-chat "show me my spend" command.
- Claude: check usage and spend at console.anthropic.com if you're on an API key, or your subscription's usage page if you're on Pro/Max.
- Codex / OpenAI: usage shows up on the OpenAI platform usage dashboard.
- Ollama: no usage cost at all beyond the VPS's own CPU/RAM — everything runs locally.
Summary
This guide expands on operating NanoClaw AI agents on a Self-Managed VPS or Virtual Dedicated Server (VDS), detailing everyday usage and powerful management features. Users learn how to maintain conversational memory and durable agent states, create multiple isolated agent groups, and leverage the ncl CLI for comprehensive resource control. It covers switching between AI providers like Claude, Codex, OpenCode, and Ollama to optimize workloads. The approval workflow ensures secure, auditable control over sensitive agent actions. Guidance on backing up critical data, migrating installations between servers, and performing clean uninstallations is included to safeguard deployments. Lastly, the guide clarifies cost responsibilities tied to AI provider usage. Together, these elements equip administrators to run scalable, secure, and efficient AI agent frameworks in their server environments.