Bots

A bot is a second agent living on your machine, beside the one you already have. It has its own memory, its own keys, its own skills and its own permissions. Nothing it learns reaches your main agent, and nothing your main agent knows reaches it.

You might keep one for work and one for personal life. One that can run shell commands and one that cannot. One with your calendar connected and one with nothing connected at all.

What a bot has of its own

Every bot gets its own directory under ~/.flowly/profiles/<name>/, holding:

Its settings, its search index, its memory store and its knowledge graph sit alongside those as files in the same directory.

Nothing in that list is shared. Two bots on the same machine cannot read each other's conversations, keys or memory.

What a bot is not

Flowly uses the word agent for three different things, and only one of them is a bot. They are easy to mix up because Desktop puts two of them under the same tab.

A bot is the only one of the three that is yours to name, configure and talk to. The other two are things an agent reaches for while it works; see Delegation for those.

Naming

A bot's name must be lowercase letters, digits, dashes or underscores, start with a letter or digit, and be at most 64 characters. These names are reserved and cannot be used: flowly, default, test, tmp, root, sudo.

The name is the bot's identity on disk and never changes. What you see in the app is its display name, which you can change whenever you like.

What a bot looks like

Every bot gets its own little woven symbol and its own colour. Flowly draws the symbol from the bot's name and the moment you made it, so no two bots get the same one. It never changes, which is how you tell two bots apart at a glance — in a group, in the sidebar, or next to a message.

Your main agent is the exception: it wears the Flowly symbol rather than a generated knot.

Creating a bot

You can create a bot empty, or clone an existing one to inherit its setup — its provider, model, persona and skills.

What a clone never inherits

A copy gets the setup, not the identity. Flowly removes the things that would let two bots pretend to be the same one.

Its connections to Telegram, Discord, Slack and the rest are removed — not switched off, removed. If they were only switched off, the passwords for those accounts would sit inside every bot you ever copied. Change the password in the original later and none of the copies would know, and each of them would still be holding the old one.

Its key for talking to your other devices is cleared. That key is how your phone and your desktop know they are reaching your Flowly. Two bots holding the same one is not sharing — it is two bots each answering as if it were the only one.

Its registration with the Flowly relay is removed. That registration names one installation, and a copy is not that installation. Your Flowly account key is unaffected and keeps working.

Its .env file is emptied of everything but model keys. .env is a file where you can put secrets by hand. Only the keys for talking to model providers survive the copy:

ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, XAI_API_KEY, ZAI_API_KEY, ZHIPU_API_KEY, ZHIPUAI_API_KEY, VLLM_API_KEY

Anything else in that file is left out of the copy.

This happens on every copy, whether you make it in the app or from the terminal. No bot has a good reason to carry the identity of the one it was copied from.

What a clone does not copy either

By default a clone takes the setup and nothing that happened. The original bot's conversations, its memory, the pictures it made and its record of what it did all stay where they are. The new bot starts with your settings and no past.

You can ask for the past as well — --clone-all on the command line copies sessions, memory, generated media and the audit log too. Credentials are still never copied. Worth thinking about before you use it: the copy then knows everything the original knew, including anything private that ended up in its memory.

[!WARNING] Because channels are removed, a cloned bot cannot answer on Telegram or any other channel until you connect it yourself. That is deliberate: without it, two bots would reply to the same message.

Credentials

A bot you create uses its own keys, kept in its own folder. Your main agent keeps its own, separately. Neither can reach the other's.

That is why a bot you have just made cannot talk to a model until you give it a key, or point it at your Flowly account.

Model and provider

Each bot chooses its own provider and model, independently of every other bot and of your main agent. One can run on a fast, cheap model while another runs on the most capable one you have access to.

[!NOTE] The model you pick is never changed behind your back. Flowly keeps a list of models it knows about, and if yours is not on it, Flowly leaves your choice alone rather than swapping in one it recognises.

What a bot can do on its own

A bot is a whole agent, not a chat window with a different name. Each one has its own:

• Conversations, listed and deleted per bot, each able to override the model for that conversation alone
• Scheduled jobs — its own cron entries, which it can list, add, change, remove and run, with their output visible while they run
• Goals it is working towards, which you can pause, resume or stop
• Plan mode, on or off for that bot
• Approvals it is waiting on, and questions it has asked you
• Tools it may reach
• MCP servers connected to that bot alone
• Its own audit trail, in its own directory

So a bot you set up to watch something overnight keeps its schedule, its goal and its history to itself. Nothing about it appears in another bot's list.

Permissions

What a bot may do is decided per bot, not once for the whole installation.

Shell and code execution — how much a bot may run:

When it asks you first: never, only when a command is not on the allowlist, or every single time.

Codex, the coding tool Flowly can hand programming work to, is set up separately. You choose when it checks with you: only when it asks, never, after reviewing its own work, or step by step. And you choose how much of your disk it can touch: read only, write only inside its own working folder, or anywhere.

A bot you made for drafting text can be left with nothing but the model. A bot you made for real work on your machine can be given more, without that decision touching anything else.

Running and stopping

Bots start when they are needed and stop when they are not. A bot with an active turn cannot be reconfigured or deleted until that turn finishes or is stopped — the app says so rather than changing settings underneath a running answer.

Creating and deleting, safely

A bot is built in a hidden temporary directory and published in one step. A crash before that step leaves the temporary directory behind and never a half-made bot.

Deleting happens in two stages, which is why a bot is never removed while it is in the middle of an answer, and why a delete that fails halfway does not leave you with half a bot.

Deleting a bot also reaches the groups it was in. A group of three loses that member and carries on. A group of two is deleted with it, transcript and attachments included, because a group needs two members to exist.

Limits

When you reach the cap, creating another asks you to delete one first rather than failing silently. Counting and creating happen under one lock shared across processes, so Desktop and the CLI cannot race past the limit together.

Backing it up, sharing it, moving it

A bot can be written out to a file, and there are two kinds of file. The difference is whether your keys are in it.

A template is what to send someone. It carries the setup — persona, skills, model choice — and none of your keys. It is the safe one to share, and it is what you get unless you ask for a backup.

A backup is locked with a password you choose, between 12 and 1,024 characters. The password is never stored, not even in a form that could check it — lose it and the backup cannot be opened by anyone, including you. The unencrypted copy exists only for a moment in a private temporary folder and is removed before the file is handed to you, and the finished file is readable only by your user account. Backups end in .flowly-backup.

[!NOTE] Flowly never hands you a complete copy of a bot in the clear. A file with your keys in it is always encrypted first; the plaintext exists only inside the export, for as long as it takes to encrypt it.

[!NOTE] A bot must be stopped before it can be exported. An archive taken from a running bot could catch it mid-write.

Two things never travel. The note of which process currently holds the bot stays behind, because it describes this machine and not the bot. And a shortcut pointing outside the bot's own folder is refused rather than followed, so an archive can never quietly pick up data from elsewhere on your disk.

Bringing one back

Importing accepts all three kinds of file, and asks which of two things you mean:

• As a new bot (the default) — it gets a fresh identity. Use this when you are adding a copy alongside the original, so the two never get mistaken for each other.
• As a restore — it keeps its original identity. Use this when you are putting back the bot you had. If a bot with that identity already exists, the import is refused rather than creating two bots claiming to be one.

From the command line

Everything above is available without the app. Bots are profile subcommands, because a bot and a profile are the same thing (see Profiles).

flowly profile list                    # every bot on this machine
flowly profile describe work           # one bot's details
flowly profile settings work           # what it is configured with

Every command takes --json when you want to read the output from a script rather than with your eyes.

One command you are unlikely to need: flowly profile backfill-marks gives a proper symbol to bots you made before symbols existed. Until you run it, those bots make do with one guessed from their name, which often leaves two of them looking almost the same. It is safe to run at any time, and does nothing when there is nothing to fix.

Making one

# Empty
flowly profile create work --display-name "Work"

# Copy an existing bot's setup
flowly profile create work --clone-from personal --display-name "Work"

# Choose its brain up front
flowly profile create work --provider anthropic --model claude-haiku-4.5

# Give it a character
flowly profile create work --soul "You draft in a formal register."

Useful flags:

Changing and removing one

flowly profile configure work --model claude-sonnet-5
flowly profile delete work --yes

Deleting asks for --yes because it is permanent.

Backing up and moving

# Shareable template — credentials removed. This is what you get by default.
flowly profile export work --output ~/work-template

# Complete and encrypted. Asks for a password, then asks again to confirm it.
flowly profile export work --output ~/work --backup

# Bring one back
flowly profile import ~/work.flowly-backup
flowly profile import ~/work-template.tar.gz --name work2
flowly profile import ~/work.flowly-backup --restore-identity

--restore-identity keeps the archived bot's original identity, and fails if a bot with that identity already exists — so a restore can never produce two bots claiming to be one. Without it, the import arrives as a new bot.

Add --local-only to an import to strip messaging transports from whatever you are bringing in.

Talking to several at once

Two or more bots can share one conversation — a group. See Bot groups.