# Admin app (https://optakt.ai/docs/admin-app)

The admin app runs in a terminal. Open it on your agent's machine:

```bash
optakt
```

Log in with your email and password. The login is kept, so next time it opens where you were; a session unused for thirty days expires.

## Finding your way [#finding-your-way]

- The top line shows the version and which deployment you are on. The line below shows who you are and the current **agent scope**. `tab` moves to the next scope, on every screen.
- Two rows at the bottom list every key that works on the current screen. A key that does not apply tells you why.
- `↑↓` moves, Enter opens, `Esc` goes back, `q` quits. Ordinary destructive actions ask for `y` to confirm. Permanently deleting a scope requires a typed confirmation, its bot and group disconnected, and the last remaining admin making the request.

## Screens [#screens]

| Screen | What you do there |
| --- | --- |
| **Home** | See the current scope at a glance. `n` creates a new agent scope, `a` archives it, `o` restores it, `x` deletes it for good. |
| **Models** | Set the reasoning (`r`) and utility (`u`) models. See [Models](/docs/models). |
| **Members** | Add users to the scope (`a`), change their role (`c`), remove them (`d`), or leave (`l`). |
| **Integrations** | Connect model providers, Telegram, Voyage AI and ElevenLabs (`a`), disconnect (`d`), reconnect (`c`). For Telegram, `b` binds a group and `u` unbinds it. |
| **Secrets** | Create (`c`), replace (`p`), rename (`n`), destroy (`d`), lock (`l`) and unlock (`u`). See [Credentials](/docs/credentials). |
| **Spaces** | See every conversation of the scope, set a space's own models (`r`, `u`), archive (`a`) and restore (`o`). |
| **Users** | Owner only: add users (`a`), reset a password (`r`), delete (`d`), transfer ownership (`t`). |
| **Profile** | Edit your name and email (`e`), change your password (`p`), link your Telegram account (`l`). |
| **Settings** | Rename the scope (`n`), replace the licence key (`l`). On your agent's machine itself the owner can also upgrade (`u`) and tune the database (`t`). |

An archived scope or space keeps receiving messages but starts no new work, until it is restored.

## Users and passwords [#users-and-passwords]

Your password unlocks your part of the vault and is never stored. A new user gets a generated four-word password, shown once; until they change it, they can only use Profile. Resetting a password issues a new one the same way. Anything protected only by the old password is lost; a shared scope can recover through another admin. The app refuses a reset that would strand a scope's secrets and tells you to add an admin or reset while the user is logged in.

## From another computer [#from-another-computer]

The admin app connects to a local service by default. To manage your agent from another Linux or Mac computer, open an SSH tunnel to your agent's machine and connect through it:

```bash
ssh -L 9631:127.0.0.1:9631 your-server
optakt
```

Or turn on remote access during the install (the *Remote access* field, for example `0.0.0.0:9633`) and connect over TLS:

```bash
optakt --host your-server --port 9633
```

On first contact the app shows the server's certificate fingerprint and asks you to compare it with the output of `sudo optakt fingerprint` on the server. Once you confirm, it remembers the server, the way SSH does.


# Backups and export (https://optakt.ai/docs/backups)

Back up your agent's PostgreSQL database and the configuration and data folders on your agent's machine. If you configured a separate database server, take the database backup there.

## What to back up [#what-to-back-up]

| What | Linux | Mac |
| --- | --- | --- |
| **Database** `optakt` | memory, archive, history, conversations, credentials (sealed) | the same |
| **Configuration folder** | `/etc/optakt` | `~/Library/Application Support/io.optakt.one/config` |
| **Data folder** | `/var/lib/optakt` | `~/Library/Application Support/io.optakt.one/data` |

The configuration folder holds `one.env` and three keys created on the first start: `core.id` (the deployment's id), `session.key` (signs admin app logins) and `vault.key` (encrypts the keys of unlocked credentials). The data folder holds the keyring and every space's files.

Losing `vault.key` locks every credential until an admin of each scope logs in and unlocks them again. Losing `session.key` logs everyone out. Losing `core.id` changes the deployment's identity.

## Make a consistent backup [#make-a-consistent-backup]

Let active work finish, then stop Optakt One before taking the database dump and copying its folders. Stopping it keeps the database and files at the same point in time. Keep PostgreSQL running while you dump it.

On Linux, with the default database Optakt installed:

```bash
backup="optakt-backup-$(date +%Y%m%d-%H%M%S)"
mkdir "$backup" &&
sudo systemctl stop optakt-one &&
sudo -u postgres pg_dump -Fc optakt > "$backup/database.dump" &&
sudo tar -czf "$backup/files.tar.gz" /etc/optakt /var/lib/optakt &&
sudo systemctl start optakt-one
```

If a step fails, the chain stops and the service stays stopped. Resolve the error and finish the backup before starting it again.

On a Mac, stop the LaunchAgent from the installing user's session:

```bash
launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/io.optakt.one.plist"
```

Use PostgreSQL 18's `pg_dump -Fc` against the database named by `DATABASE_DSN` in your configuration, and copy both folders in the table above. That applies to a custom or remote database too: the default Linux command is not its connection string. Keep passwords out of shell history and chat.

After the dump and copies finish, start the Mac service again:

```bash
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/io.optakt.one.plist"
```

Keep the dump and folder copies together, encrypted and off the machine. Check that `pg_restore --list` can read the dump and that the saved configuration includes all three keys. A readable dump is not proof of recovery: test a restore on a separate machine before relying on the backup.

## Recovery [#recovery]

Recover into an empty PostgreSQL database with the required extensions installed, using the same Optakt One version as the backup. Keep the service stopped throughout:

1. Restore the database with PostgreSQL's `pg_restore`, using the database owner and connection for the recovering installation.
2. Restore the configuration and data folders, preserving their permissions and ownership. On Linux the service runs as `optakt`; on a Mac it runs as the installing user.
3. Keep the saved `core.id`, `session.key` and `vault.key`. Do not substitute keys from a fresh installation. Set `DATABASE_DSN` to the restored database if its address changed.
4. Start the service and check its logs, then open the admin app and check the scopes, spaces and credentials. Only upgrade after this recovery works.

A licence is tied to a machine. If recovering onto a different machine, write to [max@optakt.io](mailto:max@optakt.io) to release or replace the old activation.

Do not overwrite a working database to test a backup. For a custom database or a changed operating system, confirm the restore procedure with the person managing that server first.

## Taking everything with you [#taking-everything-with-you]

Your data is a standard PostgreSQL database and ordinary files. A coordinated dump and the folders above contain the stored records and files, readable by a system that can take them in. The credentials remain encrypted; exporting them does not make their values readable without the matching keys and passwords.


# Chat (https://optakt.ai/docs/chat)

You talk to your agent on Telegram, like you would with a person. Slack, Teams and Discord are coming soon.

## Messages [#messages]

Write what you need, in your own words. Your agent answers in formatted text, with headings, lists, tables and code where they help, and the answer appears as it is written.

It understands how you use Telegram: a **reply** to one of its messages, an **edit** of yours, a **reaction** with an emoji. It reacts and replies too.

When a job takes longer, it tells you what it is doing as it goes.

## Files [#files]

Send documents, photos, audio or video, one at a time or as an album. Your agent receives them as one message with each file's name, size and a preview of its text.

- **Documents** are converted so the agent can read them: Word, Excel, PowerPoint, PDF, EPUB and more. A spreadsheet is read sheet by sheet.
- **Limits:** your agent can receive files of up to 20 MB each through Telegram, with ten files per album. The 20 MB limit is for bot downloads, not for what you can upload to Telegram. If a file is too large, your bot replies: “That file is too large for me to receive: the limit is 20 MB.”
- Every received original is kept on your agent's machine, in the space's folder.

Your agent sends files back the same way: up to ten at once, up to 50 MB each. It can also edit Word, Excel and PowerPoint files, including comments and tracked changes in Word.

## Voice notes [#voice-notes]

Send a voice or video note and your agent receives what you said, as text. [ElevenLabs](/docs/optional-services#elevenlabs) is recommended if you want to use voice notes. With it connected, ElevenLabs transcribes them; otherwise, or when ElevenLabs fails, transcription runs on your agent's machine.

## Settings for one conversation [#settings-for-one-conversation]

These commands change the model settings of the conversation you send them in, and nothing else:

| Command | What it sets |
| --- | --- |
| `/model` | The model |
| `/thinking` | Whether the model thinks before answering |
| `/effort` | How hard it thinks |
| `/budget` | How many tokens it may think with |
| `/maxoutput` | The longest answer it may write |

Send a command on its own to see the current setting and choose from a menu. See [Models](/docs/models).


# Commands (https://optakt.ai/docs/commands)

## On your agent's machine [#on-your-agents-machine]

| Command | What it does |
| --- | --- |
| `curl -fsSL https://get.optakt.ai \| bash` | Installs, or upgrades an existing installation |
| `optakt` | Opens the [admin app](/docs/admin-app) |
| `optakt --host <host> --port <port>` | Opens the admin app on another machine |
| `sudo optakt install` | Runs the installer, or continues one that stopped |
| `sudo optakt upgrade` | [Upgrades](/docs/upgrade) to the newest release your licence allows |
| `sudo optakt tune` | Tunes an Optakt-managed database, restarting it if needed. For a server you manage, it sets database-local values and reports server-wide changes for you to apply |
| `sudo optakt fingerprint` | Prints the certificate fingerprint for remote access |
| `optakt version` | Prints the version |
| `optakt help [command]` | Prints help |

On a Mac, run them without `sudo`.

`optakt-secret` is installed beside the service. Your agent's commands use it to fill in a credential; it is not meant to be run by hand.

## In the chat [#in-the-chat]

Each of these applies to the conversation you send it in. Sent on its own, it shows the current setting with a menu.

| Command | What it sets |
| --- | --- |
| `/model` | The model |
| `/thinking` | Whether the model thinks before answering |
| `/effort` | How hard it thinks |
| `/budget` | How many tokens it may think with |
| `/maxoutput` | The longest answer it may write |


# Configuration (https://optakt.ai/docs/configuration)

Almost everything is configured in the [admin app](/docs/admin-app) and stored in the database: users, agent scopes, models, integrations and credentials. One file holds what the service needs before it can reach its database.

## one.env [#oneenv]

On Linux `/etc/optakt/one.env`, on a Mac `one.env` in the configuration folder. The installer writes it, and [upgrades](/docs/upgrade) keep it current.

| Variable | What it sets |
| --- | --- |
| `DATABASE_DSN` | How the service reaches its database |
| `OPTAKT_CONFIG_DIR` | The configuration folder (default `/etc/optakt`) |
| `OPTAKT_DATA_DIR` | The data folder (default `/var/lib/optakt`) |
| `LICENSE_KEY` | Your licence key |
| `CAPABILITIES_REMOTE_ADDRESS` | Remote access for the admin app over TLS, for example `0.0.0.0:9633`. Off when empty |
| `LOG_LEVEL` | `trace`, `debug`, `info`, `warn` or `error` |

Restart the service after a change: `sudo systemctl restart optakt-one` on Linux; `launchctl kickstart -k "gui/$(id -u)/io.optakt.one"` on a Mac, from the installing user's session.

The service's management interface listens only on your agent's machine by default; remote access goes through an SSH tunnel or the TLS address above.

## Where everything lives [#where-everything-lives]

| Location | Linux | Mac |
| --- | --- | --- |
| Commands | `/usr/local/bin` | `~/Library/Application Support/io.optakt.one/bin`, with `optakt` linked into `/usr/local/bin` |
| Configuration | `/etc/optakt` | `~/Library/Application Support/io.optakt.one/config` |
| Data, keyring and spaces | `/var/lib/optakt` | `~/Library/Application Support/io.optakt.one/data` |
| Document and voice tools | `/var/lib/optakt/tools` | `tools` in the data folder |
| The agent's home | `/home/optakt` | your home |
| Service | systemd unit `optakt-one`, user `optakt` | LaunchAgent `io.optakt.one` |
| Logs | `journalctl -u optakt-one`, install log `/var/log/optakt-install.log` | `~/Library/Logs/io.optakt.one` |

Each space has its own working folder under `spaces` in the data folder, where your agent's commands start and received files are kept.


# Credentials and integrations (https://optakt.ai/docs/credentials)

## Credentials stay sealed [#credentials-stay-sealed]

API keys, tokens and passwords are kept in a vault on your agent's machine, encrypted, and belong to one [agent scope](/docs/spaces). Your agent uses a credential by its name inside the command that needs it. The value is filled in for that command, rather than being given to the model as setup data. Keep commands and connected tools from printing credentials: their output can enter the conversation.

## Adding a credential [#adding-a-credential]

- **In the admin app:** open Secrets, press `c`, and enter a name and the value.
- **By signing in:** for services with a sign-in flow, your agent starts it and sends you a link or a code. You approve on your own device; the token goes straight into the vault.

Never paste a credential into the chat. A message is stored in the history and sent to your model provider.

## Integrations [#integrations]

There is no catalogue of integrations to install. Add a credential, then ask your agent to learn the service: it reads the service's documentation, tries it, and writes down how it works in its memory. From then on it uses it whenever a job needs it. You just built your own integration.

## Locked and unlocked [#locked-and-unlocked]

A new credential is **unlocked**: your agent can use it at any time, across restarts.

A **locked** credential stays sealed until an admin of the scope unlocks it. Under Secrets, `l` locks and `u` unlocks; `a` selects all of them first. An admin session remembered by the app is not an open vault: after a timeout, logout or service restart, an unlock asks for the admin's password again.

## Managing them [#managing-them]

Under Secrets you can also replace a value (`p`), rename (`n`) and destroy (`d`). The credentials of Telegram, model providers, Voyage AI and ElevenLabs are managed under Integrations.


# First conversation (https://optakt.ai/docs/first-conversation)

Your agent only works for people it knows. Before it answers you, link your Telegram account to your owner account.

## Link your Telegram account [#link-your-telegram-account]

1. Open your bot on Telegram, from the link on the installer's last screen or by searching for its username. Send it any message. It answers: *I don't know you yet.*
2. On your agent's machine, open the admin app:

   ```bash
   optakt
   ```

   Log in with the email and password you chose during the install.
3. Go to **Profile** and press `l`. The app shows a one-time code, valid for ten minutes.
4. Send that code to your bot from your Telegram account. The bot confirms.

## Say hello [#say-hello]

Send your bot a message. Your agent introduces itself and asks what you want it for. Tell it in your own words: who you are, what you work on, what you would like to hand over. It takes notes as you talk, and builds on them from then on.

There is no setup beyond that. Ask it to do something real, and correct it when it gets something wrong; it keeps the correction.

## Next [#next]

- [Chat](/docs/chat): files, voice notes and how it answers.
- [Spaces and teams](/docs/spaces): a separate conversation for each project, and other people.
- [Credentials](/docs/credentials): connecting it to the services you use.


# Introduction (https://optakt.ai/docs)

Optakt One gives you an agent of your own. It runs on your agent's machine, talks with you on Telegram, and keeps what it learns: what is true now in its memory, what happened in its archive, and every message in full. You choose from the [supported models and connections](/docs/models), and it does real work on the machine it runs on.

Everything it needs comes in one install: the database, the search, the tools to read documents and voice notes, and an admin app to manage it all.

## How to get started [#how-to-get-started]

1. Check the [requirements](/docs/requirements): a Linux server or a Mac, a model provider and a Telegram account.
2. [Get a licence key](/docs/licence). The installer asks for one.
3. [Create a Telegram bot](/docs/telegram-bot). It is how you talk to your agent.
4. [Install](/docs/install) with one command.
5. [Start your first conversation](/docs/first-conversation).

## Where things are [#where-things-are]

**Working with it** explains what your agent does: [chat](/docs/chat), [spaces and teams](/docs/spaces), [memory](/docs/memory), [credentials](/docs/credentials), [models](/docs/models) and [principles](/docs/principles).

**Running it** covers the machine side: the [admin app](/docs/admin-app), [upgrades](/docs/upgrade), [backups](/docs/backups), [data and privacy](/docs/privacy) and [troubleshooting](/docs/troubleshooting).

**Reference** lists the [plans](/docs/plans), the [commands](/docs/commands), the [configuration](/docs/configuration) and the [RPC protocol](/docs/rpc).

Questions the docs don't answer go to [max@optakt.io](mailto:max@optakt.io).


# Install the agent (https://optakt.ai/docs/install)

Run this on your agent's machine—the computer or server where Optakt One will run:

```bash
curl -fsSL https://get.optakt.ai | bash
```

On the first run, paste your [licence key](/docs/licence). It is checked before anything is downloaded. The script then downloads the `optakt` command for your agent's machine, verifies it against the release checksum, and starts the installer. On Linux it asks for your sudo password once; on a Mac, only to place the `optakt` command in `/usr/local/bin`.

## The four screens [#the-four-screens]

Nothing happens on your agent's machine that a screen has not shown first.

1. **Configure Provider.** Choose your model provider and how you sign in: an API key, a subscription, or the address of a local model server. The connection is tested at once. Then choose the model your agent thinks with. You can change it later.
2. **Setup Database.** On a machine without PostgreSQL, choose *Managed by Optakt*, and PostgreSQL 18 is installed and set up for you. If you already run PostgreSQL, it stays yours: the installer uses it without taking it over, or you give it the address of a server you manage elsewhere.
3. **Deploy Service.** Name your agent, and create your owner account: name, email and password. Then paste your Telegram bot token. A shared Voyage AI key is filled in during launch; we strongly recommend your own key. ElevenLabs is recommended if you want to use voice notes. Both are [optional services](/docs/optional-services).
4. **Execute Installation.** The installer sets everything up and shows each command as it runs: the service account and folders, the database, the tools that read documents and voice notes, and the service itself. It then checks that the service answers.

The last screen links to your bot on Telegram. Enter opens the [admin app](/docs/admin-app). Next: [your first conversation](/docs/first-conversation).

## If the install stops [#if-the-install-stops]

### Using a database you manage [#using-a-database-you-manage]

An existing or remote server must run PostgreSQL 18 with `vector`, `pg_search`, `pg_trgm` and `uuid-ossp`. `pg_search` must be in `shared_preload_libraries`. The application user needs `pg_read_all_settings` to check those settings. The installer names any missing requirement and stops; it does not take over a database server you manage.

### Continuing the install [#continuing-the-install]

The installer names the check that failed and why. Fix what it names, then run it again:

```bash
sudo optakt install
```

On a Mac, `optakt install`, without sudo. It continues from what is already in place.

Every command is logged, in `/var/log/optakt-install.log` on Linux and in `~/Library/Logs/io.optakt.one/install.log` on a Mac.

## On a Mac [#on-a-mac]

Optakt One installs for the person who runs it, the way a Mac app does: everything lives under `~/Library/Application Support/io.optakt.one`, and it runs in your own session. PostgreSQL comes from [Postgres.app](https://postgresapp.com), in its own copy beside the rest.

On an Intel Mac, one database extension is built from source. The installer says so first, asks for your administrator password if Xcode's command line tools are missing, and the build can take up to two hours.

## Already installed [#already-installed]

Running the command again on a machine with a working installation offers an [upgrade](/docs/upgrade) instead.


# Get a licence (https://optakt.ai/docs/licence)

Optakt One needs a licence key to install and to run. This holds for every plan, Free included.

## During preview access [#during-preview-access]

There is no online checkout yet. To get a licence, write to [max@optakt.io](mailto:max@optakt.io) with:

- your name,
- the plan you want: Free, Solo or Team,
- for Team, how many users.

We send you your licence key by email.

## The plans [#the-plans]

| Plan | Price | For |
| --- | --- | --- |
| **Free** | €0 | One person, one space |
| **Solo** | €25 per month | One user, with a space for every project, client or theme |
| **Team** | €20 per user per month, from two users | A team with members, roles and shared spaces |

Every plan runs the whole system. The plans differ only in how many users, agent scopes and spaces the licence allows. The details are under [Plans and licences](/docs/plans).

Model costs are not included: your model provider bills you directly, under your own key or subscription.

## Where the key goes [#where-the-key-goes]

The installer asks for the key on its first run and checks it before it downloads anything. It keeps the key in `~/.optakt/license`, readable only by you. Later runs read it from there.

To replace a key, open the [admin app](/docs/admin-app), go to Settings and press `l`.

A licence runs on one machine.


# Memory (https://optakt.ai/docs/memory)

Your agent keeps three kinds of knowledge, each in its own place.

## Memory: what is true now [#memory-what-is-true-now]

Memory holds what your agent knows at this moment: who you are and how you like to work, your projects and where they stand, the people involved, how to use each of your tools. When something changes, the agent rewrites what went stale, so its memory reads as the current picture.

## Archive: what happened [#archive-what-happened]

The archive holds what happened: decisions taken, figures settled, mistakes found, each dated. Entries are never rewritten. When something later turns out wrong, the entry gets a dated correction, and the original stays readable.

So your agent can tell you both today's price and what you quoted in May, and how one became the other.

## History: every message [#history-every-message]

Every message and tool result is kept in full in the database; original files stay in the space's folder. A long conversation is condensed in stages so it fits what the model can read at once: recent work stays word for word, older work is summarised. What matters is saved to memory and the archive along the way, and the full history remains available to the agent.

## Search [#search]

Your agent finds knowledge by meaning, by wording and by how things connect. It is instructed to search before acting on a person, a project or a decision. Whether it chooses the right search and uses the result well still depends on the model.

## Where it applies [#where-it-applies]

Memory and the archive belong to the [agent scope](/docs/spaces): every space of that agent shares them, and nothing reaches another scope. The conversation itself stays with its space.

## Correcting it [#correcting-it]

When your agent gets something wrong, tell it, plainly. It is instructed to record the correction and adjust how it works at the point where it makes that kind of decision. That gives future conversations a record to draw on, not a guarantee that the model will never repeat the mistake.

You can also ask it what it knows about something, or ask it to keep or remove a memory. Removing a memory does not erase the original conversation or every archive entry about it. For deleting the underlying records, be explicit about what you want removed; backing up or retaining a copy is a separate decision.


# Models (https://optakt.ai/docs/models)

Your agent runs on the model you choose. Its memory, archive and conversations live in your own database, not with the model, so you can switch whenever you like and it carries on where it was. By default that database is on your agent's machine; you can also connect a database server you manage elsewhere.

## Providers [#providers]

| How | Options |
| --- | --- |
| **API key** | Anthropic, OpenAI, Google, xAI, DeepSeek, Moonshot, Qwen, MiniMax, Z.AI, Xiaomi MiMo, OpenRouter |
| **Subscription** | Claude, ChatGPT, Grok: connect by signing in |
| **A model server you control** | Ollama, or another server with the same interface |

The installer connects the first one. Add more in the [admin app](/docs/admin-app) under Integrations, Inference. Each addition is tested before it is saved. Your provider bills you directly; nothing passes through us.

## Two roles [#two-roles]

Each agent scope has two default models:

- **Reasoning**: the model your agent thinks and talks with.
- **Utility**: a smaller, cheaper model for background work, such as condensing long conversations and indexing names.

Set them in the admin app under Models: `r` for reasoning, `u` for utility. New spaces start with those defaults. When you change them, the app can apply the change to existing spaces too; otherwise their settings stay as they were.

If the utility model stops answering, your agent moves to the next one that works, and the admin app shows it. It does not switch back automatically when the first model recovers: select it again in the admin app. A reasoning model is never used as the utility fallback.

## One conversation on another model [#one-conversation-on-another-model]

Each space can run on its own model. Send `/model` in that conversation to pick one, or set it in the admin app under Spaces. `/thinking`, `/effort`, `/budget` and `/maxoutput` adjust how that model works, for that conversation only.


# Voyage AI and ElevenLabs (https://optakt.ai/docs/optional-services)

Both services are optional. **Voyage AI is highly recommended for search. ElevenLabs is recommended if you want to use voice notes.** Neither replaces your [model provider](/docs/models).

You can add their keys during installation or later in the [admin app](/docs/admin-app). You do not need to install either company's SDK. Optakt One connects to their APIs.

## Voyage AI [#voyage-ai]

### What it does [#what-it-does]

Voyage AI turns text into embeddings: numerical representations used to find related meaning, not just matching words. Optakt One uses them when it stores and searches memory and the archive.

Without Voyage AI, new text is not embedded. Search still has its wording and connection-based paths, but loses the meaning-based part. We strongly recommend connecting your own key.

### Our launch-period key [#our-launch-period-key]

We currently provide a shared Voyage AI key during launch, so you can start without opening an account there. This is a launch provision, not a permanent service included in your Optakt One plan. The shared key may become unavailable if its costs become unsustainable.

Your own key puts that usage under your own account rather than the shared launch allowance. If the shared key stops working, replace it with your own; do not depend on it for long-term access.

### Get and connect a key [#get-and-connect-a-key]

1. Create a Voyage AI account and open the [API keys dashboard](https://dashboard.voyageai.com/organization/api-keys).
2. Choose **Create new secret key**. Keep the key private; do not paste it into chat.
3. Open `optakt`, log in as a scope admin, and select the agent scope you want to configure.
4. Under **Integrations**, if Voyage AI is already connected with the launch key, select it and press `d` to disconnect it. Then press `a`, choose **Processing → Voyage AI**, and enter your own key.
5. The app checks the connection. Press `r` on the integration to refresh its status later.

The key belongs to that agent scope. Other scopes keep their own connection. Replacing the launch key does not erase existing memories or embeddings.

Voyage's [API key guide](https://docs.voyageai.com/docs/api-key-and-installation) covers its account-side setup. Its Python installation instructions are not needed for Optakt One.

### Costs and data [#costs-and-data]

Usage under your own key is governed and billed by Voyage AI, separately from your Optakt One licence. Check [Voyage's current pricing](https://docs.voyageai.com/docs/pricing) and the usage in your dashboard.

Voyage receives the text being embedded and the search phrases: memory and archive content and the names in it, not the full conversation history. See [Data and privacy](/docs/privacy).

## ElevenLabs [#elevenlabs]

### What it does [#what-it-does-1]

ElevenLabs transcribes voice and video notes before your agent reads them. We recommend it if you want to use voice notes.

Without it, Optakt One uses the transcription tools installed on your agent's machine. The same local fallback is used if ElevenLabs fails. You can use voice notes without an ElevenLabs account; the transcription work runs there instead.

### Get and connect a key [#get-and-connect-a-key-1]

1. Create an ElevenLabs account and open its [API key settings](https://elevenlabs.io/app/settings/api-keys).
2. Create an API key with access to speech-to-text. Make sure the account has the allowance needed for your use. Keep the key private; do not paste it into chat.
3. Open `optakt`, log in as a scope admin, and select the agent scope.
4. Under **Integrations**, press `a`, choose **Processing → ElevenLabs**, and enter the key. The app checks the connection.
5. Send your agent a voice note. It receives the transcription as text. Adding, changing or disconnecting the integration takes effect on the next note; you do not need to restart the service.

To replace a connected key, disconnect that integration with `d` and add it again with `a`. ElevenLabs also lets you restrict, expire and rotate keys: see its [API key guide](https://elevenlabs.io/docs/overview/administration/workspaces/api-keys).

### Costs and data [#costs-and-data-1]

Your account's plan, quota and API usage charges are set by ElevenLabs, separately from your Optakt One licence. Check your account's usage and [billing information](https://elevenlabs.io/docs/overview/administration/billing) rather than assuming transcription is included in your Optakt plan.

When connected, ElevenLabs receives the audio or video note for transcription. If you want those notes transcribed locally instead, disconnect the integration. See [Data and privacy](/docs/privacy).


# Plans and licences (https://optakt.ai/docs/plans)

## Plans [#plans]

| Plan | Free | Solo | Team |
| --- | --- | --- | --- |
| **Price** | €0 | €25 per month | €20 per user per month, from two users |
| **Users** | One | One | Two or more, with roles |
| **Spaces** | One | As many as you need | As many as you need |
| **For** | A personal assistant for everything | Someone moving many things forward at once | A business organizing its work across people and projects |

Every plan runs the whole system: memory, archive, search, any model, the admin app, everything on these pages. Model costs are separate, billed by your provider.

During preview access, licences are sent by email: write to [max@optakt.io](mailto:max@optakt.io). There is no online checkout yet. See [Get a licence](/docs/licence).

## What a licence counts [#what-a-licence-counts]

A licence sets three limits across your deployment:

- **Users**: accounts, the owner included.
- **Agent scopes**: agents. Your own account's private scope doesn't count.
- **Spaces**: conversations, private chats and topics alike, in all agent scopes.

Archived ones count until they are deleted.

Archiving a space does not free a place. Deleting a topic in Telegram permanently removes its corresponding space. A private-chat root cannot be deleted on its own; it goes with its user. Disconnect the scope's bot before permanently deleting a shared space through the management interface.

## At the limit [#at-the-limit]

Creating one more user, scope or space than the licence allows is refused, and the admin app names the limit, for example *the license allows 1 space*. Nothing that exists is ever removed. If a new licence allows less than you already have, the service starts as before and refuses new ones until you delete some or the licence allows more.

## Validity [#validity]

A licence runs on one machine. The service checks it when it starts and does not run without a valid one; while it runs, it checks in every hour.

To change plans, write to [max@optakt.io](mailto:max@optakt.io). Replace the key in the admin app under Settings with `l`.


# Principles and approvals (https://optakt.ai/docs/principles)

Your agent arrives with a constitution: values and working standards for honesty, care, verification and staying within your agreement. It is not a list of jobs. It shapes how the agent approaches whatever you work on together.

## Set the agreement [#set-the-agreement]

Tell your agent what it is for, what it can do on its own, and what needs your approval. Be specific about consequential work: sending messages, spending money, changing a running service or deleting files.

For example, you can ask it to draft email for you to review rather than send it. A continuing agreement belongs in memory, so it stays available beyond the conversation where you first said it. Ask the agent to state the agreement back before relying on it.

Instructions guide a model's choices. They are not operating-system permissions and do not make a command impossible to run. Limit the service account's access and the credentials you give it to the work it needs. See [Data and privacy](/docs/privacy).

## Corrections become principles [#corrections-become-principles]

When something goes wrong, tell the agent what was wrong and what you intended. It records the incident and updates the learning that should guide the next decision.

A useful correction teaches the judgment behind the case, not just an exception to remember. “Check the current invoice before calling it unpaid” reaches more than “that invoice was already paid”. See [Memory](/docs/memory).

## Keep human decisions human [#keep-human-decisions-human]

An unclear request is a question to resolve, not permission to guess. Review sensitive drafts and verify important results. The agent can help you check them, but a polished answer is not proof that the underlying fact is right.


# Data and privacy (https://optakt.ai/docs/privacy)

Optakt One runs on your agent's machine. What your agent knows is stored in your own database, and nothing of it reaches Optakt Labs.

## What stays on your agent's machine [#what-stays-on-your-agents-machine]

- Memory, archive and every conversation, in your own database. By default it runs on your agent's machine; if you configure a separate database server, that knowledge is stored there instead.
- Every file sent to your agent, and every file it works on.
- Credentials, encrypted in the vault.

## What leaves it [#what-leaves-it]

These are the outside services used during normal operation, and what each receives:

| Service | What it receives | Why |
| --- | --- | --- |
| **Your model provider** | The conversation and the context your agent works with, on every step | To think and answer. Under your own key or subscription, and that provider's terms |
| **Telegram** | Your messages and your agent's answers | It is the chat you talk in |
| **Voyage AI** | Text from memory and the archive, the names in it, and what your agent searches for. Not the conversations | To turn it into embeddings for search. We provide a shared key during launch, but it may be withdrawn if costs become unsustainable. Your own key is highly recommended |
| **ElevenLabs**, if connected | Your voice and video notes | To transcribe them. Without it, they are transcribed on your agent's machine |
| **Keygen**, our licensing service | Your licence and account details, a hashed id of your agent's machine, and a check-in every hour | To validate your licence |
| **The services you connect** | What each job needs | Your agent uses them on your behalf |

With a model running on hardware you control, the conversation is not sent to an outside model provider. Telegram still carries your messages. To stop sending text to Voyage AI, disconnect it under Integrations. New text is then no longer embedded, and search keeps working by wording and connections, with less reach by meaning.

See [Voyage AI and ElevenLabs](/docs/optional-services) for how to connect your own accounts and manage their usage.

## What your agent can do on its machine [#what-your-agent-can-do-on-its-machine]

Your agent runs commands on its machine, as the service's own user (`optakt` on Linux, you on a Mac), with that user's rights. That is how it does real work: files, scripts, tools, the services you connect.

There is no sandbox around those commands yet. Give the agent only the access its work needs: run it on a machine of its own, or keep that user's rights limited. A sandboxed environment for every space is coming soon.

Documents and voice notes are a different matter: the tools that convert them always run sandboxed, without network.


# Requirements (https://optakt.ai/docs/requirements)

## Your agent's machine [#your-agents-machine]

This is the computer or server running Optakt One. **Your device** is where you use Telegram. They can be the same computer, or separate devices.

Optakt One runs on Linux or Mac:

- **Linux** with systemd. Standard automatic setup covers the Debian/Ubuntu and Fedora/RHEL families; other distributions may need manual dependency setup. The install needs root.
- **macOS** 10.15 or later, with [Homebrew](https://brew.sh). It installs for the person who runs it, without root.

There is no Windows version.

Your agent works while its machine is on. A server, rented or your own, keeps it available around the clock; the computer on your desk works too, as long as it is running.

On a Mac with an Intel processor, one database extension is built from source during the install. That step can take up to two hours. On Apple silicon it is a download.

## A model provider [#a-model-provider]

One of these, and the installer tests it before going on:

- **An API key** from Anthropic, OpenAI, Google, xAI, DeepSeek, Moonshot, Qwen, MiniMax, Z.AI, Xiaomi MiMo or OpenRouter.
- **A subscription** you already pay for: Claude, ChatGPT or Grok, connected by signing in.
- **A model server you control**, such as Ollama, running on your agent's machine or another computer you control.

See [Models](/docs/models) for how the agent uses them.

## A Telegram bot [#a-telegram-bot]

You talk to your agent on Telegram, through a bot of your own. Creating one takes two minutes: see [Create a Telegram bot](/docs/telegram-bot).

## A licence key [#a-licence-key]

The installer asks for it on the first run. See [Get a licence](/docs/licence).

## Optional [#optional]

- **Voyage AI — highly recommended for meaning-based search.** We provide a shared key during launch, but it may become unavailable if the costs become unsustainable. We strongly recommend connecting your own key for continued access.
- **ElevenLabs — recommended if you want to use voice notes.** It transcribes voice and video notes. Without it, transcription runs on your agent's machine.

See [Voyage AI and ElevenLabs](/docs/optional-services) for accounts, API keys, connection steps, costs and the local alternatives.


# RPC protocol (https://optakt.ai/docs/rpc)

Optakt One exposes Cap'n Proto RPC interfaces. The admin app uses these interfaces too: a custom client can manage the same deployment without writing directly to its database.

This is a typed RPC protocol, not a REST or HTTP JSON API. A client needs the matching schemas and bindings. To obtain the protocol for your integration, write to [max@optakt.io](mailto:max@optakt.io).

## Management [#management]

The **Capabilities** interface is the management surface. It covers login, your profile and linked identities, users, agent scopes, members, spaces, credentials, providers, integrations and model settings.

A client first obtains the authentication interface, logs in, then obtains a session using the token. The session grants operations according to the user's role. A custom interface does not bypass membership or admin permissions.

The built-in admin app connects locally by default. For a remote client, use an SSH tunnel or enable the TLS listener and verify its certificate. See [Admin app](/docs/admin-app#from-another-computer).

## Service interfaces [#service-interfaces]

Three other interfaces serve the system's components:

| Interface | What it carries |
| --- | --- |
| **Engine** | Workloads, results, streaming tokens, tool calls and model/provider configuration |
| **Messenger** | Messages, files, reactions, bot configuration and chat updates |
| **Events** | Workload accepted/completed notifications for observers |

The Engine and Messenger interfaces are two-sided: each service supplies capabilities to the other during a handshake. They are component contracts, not an unauthenticated endpoint for submitting chat messages.

## Compatibility [#compatibility]

Use schemas that match the version of the deployment you connect to. Before building a new client or connector, agree which interface it needs; the management API, a chat connector and an execution component serve different purposes.


# Spaces and teams (https://optakt.ai/docs/spaces)

## Scopes and spaces [#scopes-and-spaces]

A **space** is one conversation with your agent. Your private chat with the bot is a space. So is each topic in a Telegram group. A space is created when its first message arrives.

An **agent scope** groups spaces around one agent, with its own Telegram bot, members, memory and archive, credentials and models.

Spaces in the same scope share memory and archive: what your agent learns in one conversation is available in the others. You can keep projects in separate conversations without cutting them off from that shared learning. Each space keeps its own conversation, files and, if you like, its own model.

Separate scopes isolate groups of spaces from one another, including their knowledge, credentials and membership. That can be useful when they must stay apart, but you also give up shared learning: what an agent learns in one scope is not available in another. For work that should build on the same knowledge, use different spaces within one scope.

## A space for every project [#a-space-for-every-project]

To work on several things in parallel, give each its own space:

- **In a private chat,** turn on topics for your bot in @BotFather. Each topic of the chat becomes a space of its own.
- **In a group,** turn on topics in the group's settings. Each topic becomes a space.

How many spaces you can have depends on your [plan](/docs/plans).

## Working as a team [#working-as-a-team]

1. **Add people.** The owner adds users in the [admin app](/docs/admin-app) under Users, with a name and an email. The app shows a four-word initial password, once; pass it on securely. Each person opens the admin app, logs in, and changes that password under Profile with `p`. Until then only Profile is available. They then link their own Telegram account, as in [First conversation](/docs/first-conversation). For a server, see [remote access](/docs/admin-app#from-another-computer).
2. **Make them members.** Under Members, add each user to the agent scope as `admin` or `member`. Admins manage the scope; members work with it.
3. **Bind a group.** Create a Telegram group, add the bot and make it an administrator. Then, under Integrations, select Telegram and press `b` to bind the group to the agent scope. One of the scope's admins must have linked their Telegram identity and be an administrator of the group too. A scope can bind one group.

If the bot loses its admin role, or no linked scope admin remains a group admin, the group's spaces are archived. Private conversations are not affected.

## Who can manage an agent [#who-can-manage-an-agent]

Scope admins manage membership, credentials, providers and models. The last admin cannot leave or be removed or demoted. Members can work with the agent but cannot change that setup.

The deployment owner can see every scope's bot and membership and can join a scope as an admin. He must join before seeing its spaces. Separate scopes keep knowledge apart during agent operation; they do not hide it from the person administering the deployment.

## Who starts work [#who-starts-work]

In a group, your agent reads every message as context, but only a member starts work, by mentioning the bot (`@your_bot`). A reply to the bot without the mention is read, not acted on. A message from someone who is not a member is kept and never acted on.

In a private chat, every message from a linked member starts work. Someone who is not a member is told to ask an admin.

Membership is managed in the admin app, never in Telegram.


# Create a Telegram bot (https://optakt.ai/docs/telegram-bot)

Your agent needs a Telegram bot: the account it answers from. You create it with @BotFather, Telegram's own bot for making bots, and the installer asks for its token.

## Create the bot [#create-the-bot]

1. Open Telegram and start a chat with [@BotFather](https://t.me/BotFather). Check the blue verified mark next to its name.
2. Send `/newbot`.
3. Send the name people will see, for example *Ada*. It can be anything.
4. Send a username for the bot. It must end in `bot` or `Bot`, for example `ada_assistant_bot` or `AdaAssistantBot`, and nobody else may have it already.
5. BotFather answers with a **token**, a long line like `7712345678:AAH…`. Copy it.

That token is what the installer asks for. Treat it like a password: whoever has it can speak as your bot.

## Later [#later]

- **One bot per agent.** The bot belongs to its agent scope. A second agent needs a second bot.
- **In a group,** the bot needs to be an administrator. See [Spaces and teams](/docs/spaces).
- **A lost or leaked token** can be revoked in @BotFather with `/revoke`. In the [admin app](/docs/admin-app), select Telegram under Integrations and press `c` to reconnect with the new token. To use a different bot, disconnect the existing integration first, then connect the new bot.


# Troubleshooting (https://optakt.ai/docs/troubleshooting)

## The install stopped [#the-install-stopped]

The installer names the check that failed. Fix it and run `sudo optakt install` again (on a Mac, `optakt install`); it picks up where it stopped. The full log is in `/var/log/optakt-install.log`, or `~/Library/Logs/io.optakt.one/install.log` on a Mac.

## The bot doesn't answer [#the-bot-doesnt-answer]

- **It says *I don't know you yet*.** Link your Telegram account: admin app, Profile, `l`, then send the code to the bot. See [First conversation](/docs/first-conversation).
- **It says you are not a member.** An admin of the agent scope adds you under Members.
- **In a group,** mention the bot (`@your_bot`); other messages, replies to the bot included, are read as context only. The bot must be an administrator of the group. See [Spaces and teams](/docs/spaces).
- **Nothing at all.** Check that the service runs:

  ```bash
  systemctl status optakt-one
  journalctl -u optakt-one --since "-15 min"
  ```

  On a Mac, the logs are in `~/Library/Logs/io.optakt.one`.

## The service doesn't start [#the-service-doesnt-start]

The service checks its licence when it starts, and does not run without a valid one. The log says why. If a refused or expired key prevents it starting, rerun `curl -fsSL https://get.optakt.ai | bash`: the bootstrap asks for a replacement key. If the service is still running, replace it in the admin app under Settings with `l`. For a new key, write to [max@optakt.io](mailto:max@optakt.io).

## The licence has no room [#the-licence-has-no-room]

Creating a user, an agent scope or a space beyond what your licence allows is refused, with the limit named. Nothing that exists is removed. Archived ones count until they are deleted. See [Plans and licences](/docs/plans).

## A file arrives without a preview [#a-file-arrives-without-a-preview]

The converter for that file type failed. The original is still stored and your agent still gets the message, with the reason. Running the upgrade again reinstalls the converters:

```bash
sudo optakt upgrade
```

On a Mac, run `optakt upgrade` without sudo.

## Still stuck [#still-stuck]

Write to [max@optakt.io](mailto:max@optakt.io) with what you did, what you expected, and the relevant lines of the log.


# Upgrade (https://optakt.ai/docs/upgrade)

Make a [backup](/docs/backups) first. Database migrations are not reversible; a preflight check is not a backup or a promise that a later failure can be rolled back.

Run the install command again. It brings the newest `optakt` command and offers the upgrade:

```bash
curl -fsSL https://get.optakt.ai | bash
```

If the `optakt` command is already current:

```bash
sudo optakt upgrade
```

On a Mac, `optakt upgrade`, without sudo. In the [admin app](/docs/admin-app), the owner can also start it from Settings with `u`.

## What an upgrade does [#what-an-upgrade-does]

1. On a standard deployment it first tries the new version's database changes on your data and rolls them back. If the database cannot be reached or a change fails, it stops before replacing the service.
2. It downloads and verifies the new release.
3. It brings the service and its configuration in line with the new version, and restarts it. It tunes an Optakt-managed database; for a server you manage, it reports server-wide settings for you to apply.
4. It checks that the service answers, and ends with a list of anything you should know.

Your configuration file is kept as it was, as `one.env.previous`, whenever the upgrade changes it.

Upgrades follow the channel your licence allows.

If an older or nonstandard installation needs its folders repaired, that repair comes first and stops the service. A failed repair leaves it stopped at the point it reached. Read the named error and rerun the upgrade after fixing it; do not treat this as a transactional database rollback.