The first hour with a new node, in order. At the end, people can reach it, an agent can work in it, and you have restored a backup once.
Install Stuga on your platform:
Check: on the node's machine, curl -s http://127.0.0.1:8787/ready answers {"ok":true}. The
node's log has a line like this, which names the address, whether anyone has claimed the node yet,
its identity provider and whether AI is on, and while nobody has, the link that sets it up:
[node] listening on http://0.0.0.0:8787 (public origin http://192.168.1.50:8787, unclaimed, identity provider none, ai off)
[node] nobody has set up this node yet. Open http://192.168.1.50:8787/login?setup=7KD2M-X9QPA to create its administrator (setup code 7KD2M-X9QPA).
Open the setup link: the Mac package and install.sh open or print it, and the node's log has it. A node nobody has claimed
opens on Welcome to Stuga: pick a username and a password and choose Create administrator
account. The link carries the node's setup code. Opened at the node's plain address instead, the
page asks for the code. On a Mac, Set Up Stuga… in the menu bar opens the page with it filled in,
and Copy Setup Link copies that link for another browser;
with Docker, ./stuga status prints the link. The log shows it too, and the node keeps it in
DATA_DIR/setup-code until it is claimed. Only whoever holds the code can claim the node, so it is safe on a network from its first
start.
You sign in with the username; an email is optional, and you can add one later under Settings → Profile. The first account administers the node: it configures AI, appoints other administrators and recovers accounts. Its password stays a way in even after you add an identity provider. From then on an account is created only with an invite link.
Check for new versions on that page is ticked: once a day the node asks GitHub for the list of releases, says nothing about itself, and tells its administrators when a newer one is out. Untick it on a node that cannot or should not reach the internet, and the node never asks (Operations). The next page reads the list of samples from GitHub as well, unless SAMPLES_URL points the node at a mirror.
Check: the node's log says first account created; it administers this node.
Stuga asks you to Create your workspace. Documents, databases, members and permissions all belong to one workspace, and nothing crosses between workspaces. You can add more later. The workspace switcher in the top bar lists them, and Add another node… there keeps a shortcut to another Stuga node (Several nodes).
Start with picks what the workspace holds at first:
- Empty.
- Sample, then a sample such as Privacy laws: a workspace of real, openly licensed material. The node reads the list of samples from github.com/stuga-dev/samples when the page or dialog opens, keeps it an hour, and downloads the sample you choose when you create the workspace. When its last look for the list failed, as it does without internet access, it says Samples need an internet connection; SAMPLES_URL points the node at a mirror. The new workspace opens at the sample's Start here document. Sample agent's changes, written in advance, wait for your review in Review AI edits, and its comment mentions you.
- Import: a
.stuga.zipexported from Stuga (Workspace archive), a Notion export, or a zipped Obsidian vault or other folder of Markdown (Importing from Notion or Obsidian). With no name typed, the workspace keeps the one it had: a Notion export its Notion workspace's, a vault its folder's.
Check: you reach the document list and can create a document.
AI comes in three ways, each optional and each set up on its own:
- Your AI agents: Claude, Codex or another agent connects over MCP and brings its own model, so a subscription you already have is enough and the node needs no key. It is yours alone: the agent acts with your access, and each member connects their own. See 5. Connect an agent.
- Built-in AI (chat): the co-author, Ask and the table assistant, for every member of the node, on the API key you enter (or a local Ollama).
- Semantic search (embeddings): finds documents by meaning, even when the words differ, in the search box, Ask and agents.
Nothing is sent to any model until you set one up, and documents, collaboration and keyword search work without any of them, so you can skip this step.
Right after you create the first workspace, Stuga shows all three, each with its own Set up, and Start using Stuga when you are done. Later, your own agent is in Settings → Your AI agents, and the other two are in Settings → This node → AI providers, each set up the same way:
- Choose Set up, then a Service, and enter its API key unless it is a local server. For a local Ollama, choose Ollama (local). The address it fills in is the right one for your platform.
- Choose a Model. The list comes from the service, newest first, which also shows that the key works. For Semantic search, choose one that returns at most the node's vector width, 1024 by default.
- Click Connect.
That turns it on; there is no switch to turn on afterwards. Your own agent, such as Claude Desktop, needs no Built-in AI, since it brings the model; Semantic search still helps it find text. A chat-only service such as Anthropic leaves search matching words until Semantic search is set up on another service.
Once either is set up, its switch turns it off and keeps it, and Remove forgets it. Offer more of a provider's models from its Edit.
Check: Test in a provider's Edit answers Answered. Otherwise it says what went wrong.
Troubleshooting covers the usual causes.
Open Settings → Your AI agents, or choose Set up under Your AI agents right after you create the first workspace. It has a tab for each kind of client, with the setup for this node filled in, and lists the agents you have connected so far. Each member connects their own. Agents covers each client, and how one agent works with several nodes.
Most clients sign in through your browser. The node then asks which of your workspaces the app may use, and whether it may suggest changes or only read (Apps that sign in). One connection reaches every workspace you tick.
What the client stores is simply Stuga, whatever the node is called. Name the node under Settings → This node → Branding anyway: that name is how agents are told which node a call lands on, and how each workspace is labelled when you have more than one node (One connection).
An agent never changes a document silently. Its edits wait for review, you are notified, and Review AI edits in the sidebar lists everything waiting. To let AI edits to one document or database apply directly, open it and choose Let AI edits apply directly from the ⋯ menu beside Share. Those changes are still recorded, attributed and revertible.
Check: ask the agent to propose an edit, and accept it in the document.
Other devices can reach the node only once it listens on the network and its address is right. Network access covers that, and what plain http on a network exposes.
Then open Settings → This workspace → Members. Add people adds someone who already has an account on this node: type part of their username or name and pick them from the list. For anyone else, Create link makes an invite link: it is the only way to get a new account on the node. Choose the role they join as, how many times the link can be used (once, 5, 10 or 25 times, or no limit), and whether it expires after 1, 7 or 30 days or never. An admin link can be used once. Invite links lists every link that still works, with how often it was used, and revokes one when it should stop. Invite links carry the node's address, so create them after any change to it.
If people should sign in with an organization's accounts, add its identity provider in Settings → This node → Access before you invite them. Whoever opens an invite link can then choose Continue with the provider instead of a password (Identity provider).
Check: someone opens the invite link on their own device, creates an account and sees the workspace.
Take a backup, then restore it, while nothing is at stake:
- Docker:
./stuga backup, then./stuga restore <backup>. - macOS: Back up now under Settings → This node → Backups, then run the command its
Restore… shows on the Mac,
sudo "/Library/Application Support/Stuga/current/bin/stuga" restore <backup>(install/macos.md).
A restore keeps what it replaced, so the drill loses nothing. Operations describes backups and restores in full, including why a backup is secret.
Check: the document you created in step 3 is still there.
- Configuration: every environment variable, and what Settings holds.
- Operations: backups, restores, upgrades and account recovery.
- Troubleshooting: starts from what you see.