AGENTS.md

Welcome to the Outline Monorepo!

This document provides a guide for AI and human agents working with the Outline codebase.

Repository Structure

The Outline monorepo is organized into three main components:

• /client: The Outline Client application, available on all major platforms. See client/AGENTS.md.
• /server_manager: A graphical application to create and manage Outline Servers. See server_manager/AGENTS.md.
• /infrastructure: The build system and shared TypeScript utilities. See infrastructure/AGENTS.md.

The npm run action Command

The primary entry point for all development tasks is npm run action <path>, which resolves to .action.sh or .action.mjs files in the repo. Run npm run action list to see all available actions. Pass flags after --:

npm run action client/src/cordova/setup macos -- --buildMode=release

Common Actions

• npm run action list: Lists all available actions.
• npm run action client/web/start: Starts a dev server for the shared web UI.
• npm run action server_manager/www/start: Starts a dev server for the Manager UI.
• npm run action <component>/test: Runs tests (e.g. npm run action client/web/test).
• npm run action <component>/build: Builds a component (e.g. npm run action client/electron/build linux).

Other useful commands

• npm run reset: Clean and reinstall all dependencies (fixes most build issues).
• npm run storybook: Launch the Storybook UI component explorer.
• npm run lint:gts: Lint TypeScript (pass filepaths on macOS; works on all files on Linux).

Code Style

• TypeScript: Follows Google's TypeScript style, enforced by gts. Run npm run lint:gts to check and npm run format:all to auto-fix (Linux only for whole codebase; pass specific filepaths on macOS).
• Go: Follows standard Go style. Use gofmt and go vet.

Requirements

Component	Version
Node.js	22 — run nvm use if you have nvm
Go	1.22+

Platform-specific requirements (Android SDK, Xcode, zig for cross-compilation) are documented in the relevant subdirectory AGENTS.md files.

Common Concepts

• Access Keys: Credentials used by Outline clients to connect to an Outline server. Generated by the Outline Manager.
• Shadowbox: The core proxy component of Outline, responsible for handling network traffic.
• Outline Client: The end-user application for connecting to the internet through an Outline server.
• Server Manager: The application used to create and manage Outline servers on cloud providers.
• Electron: Framework used to build the desktop versions of the Outline Client and Server Manager.
• Cordova: Framework used to build the mobile (iOS/Android) and macOS versions of the Outline Client.
• Lit: The UI framework for web components. All new components use Lit. The client has fully migrated; the server_manager still has legacy Polymer components in its app shell being migrated.
• OutlineAction: A custom build script (.action.sh or .action.mjs) that defines a task runnable via npm run action.