Skip to main content

Post-install

After the quickstart, complete these steps on the machine, as root. istota there runs the CLI inside the daemon container. On the local VM, run them on the Mac as yourself: the Mac's istota-stack and istota forward each command into the VM.

User profiles

Profile fields (display_name, timezone, email addresses, log/alerts channels, worker overrides, trusted email senders, disabled skills) live in the user_profiles SQLite table. They're auto-seeded the first time a user logs into the web UI, or you can pre-seed them with the CLI (the optional Ansible management role, where an estate uses it, runs the same command):

istota user ensure --name alice --display-name "Alice" \
--tz "America/Los_Angeles" --email alice@example.com

The web UI at /istota/settings lets each user edit their own profile and add per-user resources (calendars, folders, modules) without touching config.toml. Operator-supplied resources from config.toml show up alongside as read-only.

Claude authentication​

The first-run setup, in the browser or the terminal, collects a long-lived Claude Code OAuth token (the Claude subscription choice, which writes it to /srv/app/istota/secrets/claude_code_oauth_token), and the daemon writes Claude Code's credentials file from it at every start. Generate the token with claude setup-token. If you supplied it during install, Claude auth is already done — skip this section.

Only if you skipped the token at install time (and aren't using an API key under [brain.claude_code] auth = "api_key" or a native-brain provider key), authenticate manually:

istota-stack exec claude login

Open the web app​

Open the hostname you gave the setup (http://localhost:8080 on the local VM, or the --port you gave create) and sign in. Web chat works with or without Nextcloud.

Invite the bot to Talk​

With Nextcloud integration, open Talk and add the bot's user (default: istota) to a conversation. The bot automatically starts polling conversations it's a member of.

Test execution​

istota task "Hello" -u alice -x

Service management​

systemctl status istota-stack
istota-stack down && istota-stack up
istota-stack compose logs -f daemon

User workspace​

After the bot runs for the first time for a user, it creates a directory structure in the workspace. Where the workspace is depends on the storage mode: /srv/app/istota/data/workspace on the machine with local storage, the bot's Nextcloud files with full Nextcloud integration, and the workspace folder (~/Istota by default) on the local VM.

/Users/alice/
├── istota/ # Shared with user via OCS
│ ├── config/
│ │ ├── USER.md # Persistent memory
│ │ ├── TASKS.md # File-based task queue
│ │ ├── CRON.md # Scheduled jobs
│ │ └── HEARTBEAT.md # Health monitoring config
│ ├── exports/ # Bot-generated files
│ ├── scripts/ # User's reusable Python scripts
│ └── examples/ # Reference documentation
├── inbox/ # Files from email attachments
├── memories/ # Dated memories from sleep cycle (YYYY-MM-DD.md)
└── shared/ # Auto-organized files shared with bot

With Nextcloud, users can edit these files through the Nextcloud web UI, desktop client, or any text editor with WebDAV access. See per-user configuration for details on each file.

What to try next​

  • Send a message in web chat, or in Talk, and watch the bot respond
  • Edit PERSONA.md at the root of the bot's files (beside Users/) to change the bot's personality for everyone; see Persona
  • Set up a briefing for morning summaries
  • Configure scheduled jobs via CRON.md
  • Check out the skills index to see what the bot can do