# Roost

> Roost is a self-hosted home for persistent Codex agents, conversations, memory, and scheduled work.

Roost is designed for one trusted user. Keep the app private behind access controls. The host must stay running for agents and schedules to execute; the public marketing and documentation sites can be hosted separately.

For every guide in a single file, read [the complete documentation](https://docs.tryroost.dev/llms-full.txt).

## Start here

- [Roost documentation](https://docs.tryroost.dev/index.md): Roost gives your AI agents a place to keep working. Each agent has its own purpose, conversation, files, and memory. You run Roost on your own host and connect it to Codex.
- [Getting started](https://docs.tryroost.dev/getting-started.md): Create an agent with a clear job, then start a conversation. You can add schedules, files, and a shared computer when the work needs them.
- [Install and operate Roost](https://docs.tryroost.dev/install.md): The packaged installation supports Linux x64 with systemd. It includes its own Node and Codex runtimes, without replacing system-wide executables. Run setup as your normal account,
- [Read the docs with an agent](https://docs.tryroost.dev/for-agents.md): The public docs site provides plain Markdown alongside its human-readable pages. No browser automation, sign-in, JavaScript execution, or HTML scraping is needed to read these file

## Deployment

- [Choose where to run Roost](https://docs.tryroost.dev/deployment.md): For a persistent Roost installation, start with exe.dev. Its persistent Linux machine and private HTTPS proxy fit Roost's current design. A Linux x64 VPS or home server with system
- [Deploy on exe.dev](https://docs.tryroost.dev/deploy-exe-dev.md): Run Roost on an exe.dev VM so your agents can keep working while your laptop is closed. The installer handles Node, Codex, and starting Roost for you.
- [Deploy on a Linux server](https://docs.tryroost.dev/deploy-linux.md): Use the packaged installer on a persistent Linux x64 machine with systemd. This applies to a conventional VPS, a Linux VM you already operate, or an always-on home server. exe.dev 

## Use Roost

- [Agents and memory](https://docs.tryroost.dev/agents-and-memory.md): Each Roost agent has its own purpose, ongoing conversation, workspace, and Codex memory. Give agents clear responsibilities so you know where to return for a piece of work. You can
- [Automation schedules](https://docs.tryroost.dev/automations.md): Create or edit schedules in Agent settings → Automations, or ask the agent in chat. One cron schedule can cover several times each day. Existing one-time, interval, and weekday sch
- [Agent delegation](https://docs.tryroost.dev/delegation.md): Agents can hand parts of a user request to other agents without holding their own conversation open. Give each specialist a clear responsibility when creating it; the orchestrator 
- [Files and approvals](https://docs.tryroost.dev/files-and-approvals.md): Use Attach files beside the composer to send up to five files per message, 20 MB each. You can also paste screenshots or copied images directly into the message box with Cmd+V, Ctr
- [Shared computer and browser](https://docs.tryroost.dev/computer.md): Roost can show and operate the machine's existing X11 desktop. The live preview appears in the conversation when an agent uses the computer, beneath its first computer action in th
- [Dashboards](https://docs.tryroost.dev/dashboards.md): Dashboards keep useful trackers outside an agent's conversation. They are off by default. Enable Settings → Dashboards, then open an agent and choose Dashboard in its header. Conve
- [Push notifications](https://docs.tryroost.dev/notifications.md): In Settings → Notifications, choose Enable on this device and allow the browser permission prompt. Each browser or installed PWA subscribes separately. Choose Disable on this devic
- [Mobile and home-screen installation](https://docs.tryroost.dev/mobile.md): Open your Roost HTTPS address in Safari, then choose Share → Add to Home Screen and open it as a web app. Roost provides a standalone manifest, app icons, and an Apple touch icon. 

## Optional

- [Architecture](https://docs.tryroost.dev/architecture.md): Roost is one Node application with a React interface, SQLite persistence, and a server-owned queue for agent work. Codex runs locally through its app-server protocol.
- [Conversation performance — 0.1.17](https://docs.tryroost.dev/chat-performance.md): Measured on macOS with Node 24.15.0, a production Vite build, and isolated Chromium. The fixture contains 3,000 messages: alternating user, Markdown assistant, and tool activity en
- [Documentation on Railway](https://docs.tryroost.dev/deploy-docs-railway.md): Deploy the public docs as a standalone Railway service with Railway's built-in CDN. This does not deploy the private Roost app. No database, volume, Codex credentials, or agent dat
- [Run Roost on macOS](https://docs.tryroost.dev/deploy-macos.md): Run a source build on your Mac, then use a per-user LaunchAgent to keep its server running after Terminal closes. The packaged roost setup, roost server, and roost update commands 
- [Marketing website on Railway](https://docs.tryroost.dev/deploy-marketing-railway.md): Deploy the public marketing site as a separate marketing service alongside the docs service. Both are static sites; neither runs the private Roost app or needs databases, volumes, 
- [Roost on Railway](https://docs.tryroost.dev/deploy-railway.md): Railway is an advanced deployment option for the Roost app. This repository does not yet include a Railway-ready Dockerfile or a verified Railway app deployment. Use the Linux inst
- [Public websites on Vercel](https://docs.tryroost.dev/deploy-vercel.md): Use Vercel for Roost's marketing and documentation websites. Create two Vercel projects connected to the same Git repository, with separate build settings and domains. Both outputs
- [Development](https://docs.tryroost.dev/development.md): This guide covers running Roost from source and contributing to the app. For the packaged Linux installation, start with Install and operate Roost.
- [Host the public websites](https://docs.tryroost.dev/public-sites.md): Roost has two independent static websites: a marketing page and a documentation site. Deploy each output to its own domain on any static web host. Neither site needs the Roost serv
- [PWA startup](https://docs.tryroost.dev/pwa-startup.md): Initial compression and cache improvements
- [Remote desktop setup](https://docs.tryroost.dev/remote-desktop-setup.md): This guide provisions a persistent Linux desktop and browser for Roost. It is based on a setup validated on Ubuntu 24.04 amd64 with systemd. The browser profile stays on the host w