Self-hosted agent-infrastructure server: a web UI plus Slack, Linear, Plain, and GitHub agents, driving coding sessions through the Pi engine in git worktrees on your own box, or in isolated sandboxes. Supports multiple Codex and Claude subscriptions and model APIs.
More: pull-request review, diffs, automations, mobile →
Run this on Linux, macOS, or inside WSL2 on Windows. The server does not run directly from PowerShell; follow the Windows WSL2 setup first.
curl -fsSL https://raw.githubusercontent.com/tellahq/opensession/main/install.sh | bashThe recommended install also adds Tailscale, Caddy and the lego certificate helper so the private app can use HTTPS or a friendly custom domain.
curl -fsSL https://raw.githubusercontent.com/tellahq/opensession/main/install.sh | bash -s -- --tailscale --caddyFor public ingress through Cloudflare Tunnel instead of Tailscale, --cloudflare installs
cloudflared. Finish configuring either option under Settings → Domains and
ingress.
curl -fsSL https://raw.githubusercontent.com/tellahq/opensession/main/install.sh | bash -s -- --cloudflareAlready installed Open Session? You do not need to reinstall it. Follow Add Tailscale after a normal install.
On a fresh box this downloads the compiled release for your OS and
architecture, unpacks it under ~/.opensession, installs the claude CLI,
puts an opensession command on your PATH, writes a default configuration,
and installs and starts a per-user service (a LaunchAgent on macOS, a systemd --user unit on Linux). No questions. The last line it prints is a local URL,
by default http://127.0.0.1:3850. Budget 5 to 15 minutes, mostly unattended
download.
Open the URL, add a model account in Workspace → Providers, pick a repo, write a prompt, and create the session. A turn that actually runs is the proof the install works, not a health check. Connect your GitHub account later from Settings → Connections. Configure Slack, Linear, Plain, GitHub agent intake, and other integrations under Settings → Integrations; see docs/setup/github.md.
Check on it any time:
opensession doctor # verify the install and report engine readiness
opensession status # is the service up?
opensession update # upgrade in place, health-gated
opensession --help # everything elseThe installer and updater verify each Open Session release archive against its published SHA-256 sidecar before extracting it. GitHub also signs keyless build provenance for every release archive, DMG, and ZIP. To verify a manually downloaded artifact:
gh attestation verify ./opensession-linux-x64.tar.gz --repo tellahq/opensession
sha256sum --check ./opensession-linux-x64.tar.gz.sha256Use shasum -a 256 -c instead of sha256sum --check on macOS.
Or install from a source checkout instead. This is the path for self-development (sessions that modify Open Session itself) and for contributing:
git clone https://github.com/tellahq/opensession.git
cd opensession && bun install
bun run setup # interactive onboardingbun run setup runs the interactive onboarding wizard, writes the
configuration, and offers to install and start a user service. For unattended
defaults, run bun scripts/cli.ts onboard --defaults. Run
bun scripts/cli.ts --help for CLI commands. Options such as --source,
--dir, --channel, --tailscale, and --no-engine belong to install.sh;
run bash install.sh --help for the complete installer list. A source checkout
requires Bun and git.
Letting the agent improve Open Session itself? Clone your fork, not this repo. Self-sessions commit and push to
origin, anddeploy_selfadvances the pinned runtime to a descendant commit from it. Pointed attellahq/opensession, every push is rejected. Fork, clone the fork, and keep us as anupstreamremote. Config-only use (your repos, your integrations) needs no fork.
Authentication is available, and it is opt-in. By default, Open Session trusts everyone who can reach the address it binds to. GitHub sign-in can restrict access to configured team members. Keep the server on Tailscale, a private network, or behind an SSH tunnel even when sign-in is enabled. See the trust model and networking.md.
- CONCEPTS.md — projects, workspaces, chats, automations, goals
- docs/setup/ — overview, requirements, trust model
- docs/setup/install.md — bare box → running service
- docs/setup/ec2.md — provisioning a clean EC2 box
- docs/setup/networking.md — private team access, public callbacks, domains, and TLS
- CLIENTS.md — web UI, PWA, desktop shell, native app, extension
- docs/worktrees.md — how sessions map to git worktrees, and where the disk goes
- docs/repo-lifecycle.md — the
.agents/lifecycle scripts a repo commits so sessions provision and boot it themselves - docs/extending.md — adding tools, recipes, integrations and providers
- docs/security-model.md — least-privilege automations, per-user MCP/GitHub scoping, self-management boundaries
- docs/self-hosting-sandboxes.md — certified Docker, Daytona, Box, Modal, and local Firecracker MicroVM sandboxes; implemented E2B and AWS Lambda MicroVM adapters remain unavailable until live-certified
- docs/instance-configuration.md — repos, identity, branding, integrations, deployment policy
One server, five front ends — only the web UI is required, and everything else talks to the same instance. CLIENTS.md has the full tour.
| Client | Where |
|---|---|
| Web UI | served by the server itself — start here |
| PWA | the web UI on your phone's home screen (iOS push notifications require the installed PWA and an HTTPS origin) |
| macOS desktop shell (Electron) | packages/clients/mac/ |
| Native Swift app (iOS + macOS) | packages/clients/ios/ |
| Chrome extension (page context → session) | packages/clients/chrome/ |
Everything company-specific is instance configuration, not source — branding, the agent's name and persona, your repositories, integrations, automations (docs/instance-configuration.md). Point a stock install at your config and it becomes your company's agent server. No fork needed for that.
Forking is welcome — recommended, even — when you want to change what it is, not just whose it is: strip the integrations you'll never use, rebrand the client apps to your own bundle ids, hard-code opinions we left configurable. It's MIT, so you owe nothing but the license notice.
Product code lives under packages/:
packages/core/opensession-server/— Bun server, web client, runner hostpackages/core/protocol/— shared wire and record contractspackages/clients/— Chrome, native Swift, Electron, and website clients
Repository-level scripts, deployment files, documentation, the workspace manifest, and the lockfile stay at the root.
We take contributions as human-written text, not code — see CONTRIBUTING.md. Open a GitHub issue describing the change you'd like — a prompt or suggestion in plain language is exactly the right shape — and if we're aligned we'll handle the implementation. Report vulnerabilities privately — see SECURITY.md, not a public issue.
MIT License. Use it, fork it, run it commercially, build on it — the only obligation is keeping the copyright and permission notice. Contributions are accepted under the same license.