Return Architecture
Local Setup

A practical path to running the local setup.

Return Architecture is open source and installable from GitHub. This page documents the install path: prerequisites, the install command, and what to do after it finishes.

Source and issues: github.com/Theapolar/return-architecture.

Before you begin

  • A macOS machine. Linux works for the agent itself; the background service (auto-start on login) is macOS-only for now. Windows is not supported.
  • An API key from Anthropic or OpenAI (or both). Your keys stay on your machine — nothing is sent anywhere else.
  • About five minutes for setup.

Python is installed by the installer if you don't already have a compatible version.

Install

Open a terminal and run:

curl -sSL https://raw.githubusercontent.com/Theapolar/return-architecture/main/install.sh | sh

The script installs uv (a fast Python manager) if it is not already present, then installs Return Architecture as an isolated command-line tool. It typically takes one to two minutes — most of that is the download of larger dependencies like ChromaDB.

If you would rather not pipe a script into your shell, the README on GitHub documents an equivalent manual install with uv tool install or pipx install.

First run

When the install finishes, open a new terminal window so the command is registered on your PATH. Then run: 

return-architecture gui

This opens a local web page in your browser — a setup wizard that walks through pasting your API key, creating your first agent, optional Telegram setup, choosing scheduled rhythms, and installing the background service. The whole flow is about five minutes.

The page is served only from your own machine. Nothing is exposed to the internet.

After setup

Once the wizard finishes, the agent runs in the background. You reach it through Telegram if you set that up, or in the terminal with return-architecture chat <slug>.

The same local GUI stays available for any later adjustments — system prompt, model, schedules, tools, Telegram, reading the agent's letters, browsing tagged items. Run return-architecture gui whenever you want to change something.

For thoughts on day-to-day use, see operational notes. For the shape of the local environment more generally, see reference setup.

Telegram setup

Connecting a Telegram bot is optional but recommended — it is how the agent reaches you outside the GUI. The setup wizard includes the steps. In short:

  • Open Telegram and message @BotFather.
  • Send /newbot, follow the prompts, copy the token BotFather returns.
  • Send any message to your new bot in Telegram.
  • Paste the token into the wizard and click Discover chat ID.

Running on a remote server

Most people should run this on their personal machine. For those who specifically want always-on operation without their laptop running, the GitHub repository includes a server setup guide covering Tailscale with home hardware, a small VPS, and notes on what changes (and what does not) on a remote host.

Status

This is early-beta software. Things will change. If something breaks or feels off, open an issue on GitHub.