# Outline Server: a Shadowsocks proxy with a REST key API, self-hosted

> Outline Server, from Jigsaw, wraps outline-ss-server in a management layer that hands out access keys over HTTP. It is aimed at people who run their own Shadowsocks endpoint, not at people who want a hosted VPN. Here is how the pieces fit, how to start it, and where it stops being the right choice.

**OutlineFoundation/outline-server** — Outline Server, developed by Jigsaw. The Outline Server is a proxy server that runs a Shadowsocks instance and provides a REST API for access key management.

- Repository: https://github.com/OutlineFoundation/outline-server
- Website: https://getoutline.org/
- Stars: 6,255 · Forks: 878
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/outlinefoundation-outline-server

## What Outline Server actually solves for a self-hoster

Running a Shadowsocks endpoint is easy. Handing out credentials to a changing group of people, revoking them one at a time, and keeping a record of who holds what is the part that gets messy. Outline Server exists to close that gap. The README describes it as the component that provides the Shadowsocks service, via outline-ss-server, plus a service management API, and the repository splits into two parts: src/shadowbox, the core proxy server that runs and manages the Shadowsocks backend and exposes a REST API for access key management, and src/metrics_server, a REST service for optional anonymous metrics sharing.

The audience follows from that split. If you are an individual who wants a tunnel and does not want to touch a terminal, this repository is the wrong entry point; the README points those users at the Outline Manager, a ready-to-use graphical interface in a separate repository. Outline Server is for the person or small organisation that already has a Linux host and wants to own the endpoint, the keys and the revocation.

The anti-censorship claims are specific rather than general. The README lists mandatory AEAD ciphers, probing resistance, protection against replayed data, and variable packet sizes, and points to docs/shadowsocks.md for the reasoning. Those properties come from the Shadowsocks design and from outline-ss-server, which go.mod pins at github.com/Jigsaw-Code/outline-ss-server v1.7.3. Outline Server is the wrapper, not the cipher suite.

## How the proxy, the key API and the metrics service fit together

The data path is conventional. Client traffic arrives at the Shadowsocks listener and is handled by outline-ss-server, which the shadowbox component runs and manages. The management path is separate: an HTTP API for access keys, which is what lets a control panel or a script create, list and remove credentials without editing config files by hand. Those two paths are the reason the repository is TypeScript rather than a single Go binary; the management layer is Node, the proxy backend is Go, and go.mod carries both the backend dependency and the task runner used to drive the build.

The build system is worth understanding before you clone anything. package.json declares the repository private, sets workspaces to src/*, and pins engines to node 18.x.x. Its postinstall script is not a typical install step: it runs go build github.com/go-task/task/v3/cmd/task, which compiles the task runner itself. That is why the README lists Go 1.21+ alongside Node and npm as prerequisites even though the visible application code is TypeScript. Skip Go and npm install fails at postinstall.

The metrics server is opt-in by description. The README calls it a REST service for optional, anonymous metrics sharing, and it lives in its own directory rather than inside shadowbox. Nothing in the README suggests it is required for the proxy to serve traffic.

## Outline Server install and first setup on a Linux host

The README gives a short install path and defers the rest to src/shadowbox/README.md and CONTRIBUTING.md. Before any command, the prerequisites are Node LTS, named as lts/hydrogen version 18.16.0, npm 9.5.1, and Go 1.21 or newer. The Node requirement is not advisory: package.json sets engines.node to 18.x.x, so a newer major release is outside what the repository declares.

Install dependencies from the repository root. This is the step that also compiles the Go task runner through the postinstall hook, so it takes longer than a pure JavaScript install and will fail if Go is missing from PATH.

```bash
npm install
```

Start the server with the task runner the install just built. The README shows this as the way to bring shadowbox up.

```bash
./task shadowbox:start
```

When you are finished, the README's cleanup step is a single task target.

```bash
./task clean
```

What you should see after shadowbox:start is the proxy service running with its management API available; the README does not print expected output, so treat the core server's own src/shadowbox/README.md as the place to confirm ports, flags and configuration keys rather than guessing them. For anything beyond a local trial, read that file before exposing the host, because the top-level README documents no firewall, TLS or authentication settings for the API.

## Where Outline Server is the wrong tool

The clearest limitation is scope. This repository is the server. It does not ship the desktop or mobile client, and it does not ship the Outline Manager GUI; both live in other repositories that the README links to. If your actual problem is "I want a working VPN on my laptop in ten minutes", cloning this and running ./task shadowbox:start gives you a service with no client to connect to it and no graphical way to mint a key.

The second limitation is operational surface. You are running a Node management process and a Go proxy on a host you administer, and the top-level README documents neither hardening steps nor the API's authentication model. The README does not document rollback either, so a bad upgrade has no described path back; the release list shows three patch releases within a week in February 2025, server-v1.12.1, server-v1.12.2 and server-v1.12.3, which is the kind of cadence that makes a tested rollback procedure worth having before you upgrade in place.

The third is the anti-censorship promise itself. The README claims probing resistance and variable packet sizes, and cites docs/shadowsocks.md, but it makes no claim about any particular network, and it does not describe what happens when a specific censor blocks the endpoint. If your threat model includes an adversary actively targeting your server, the README offers mechanisms, not a guarantee, and you should read docs/shadowsocks.md before assuming the endpoint will survive.

Finally, maintenance: the last push to master was on 2026-05-13, and the newest release in the list is server-v1.12.3 from 2025-02-24. The repository is not archived, but the gap between the last release and the last push means you should check the commit log on master rather than assuming the tagged release reflects current work.

## Outline Server compared with running outline-ss-server directly

The honest alternative is not a different VPN product; it is the backend on its own. go.mod pulls in github.com/Jigsaw-Code/outline-ss-server v1.7.3, and that project is a standalone Shadowsocks server. Running it directly gives you the proxy and nothing else: no Node process, no npm install, no postinstall step that compiles a task runner, and no REST layer to keep alive.

What you lose is the reason Outline Server exists. Without shadowbox there is no access key API, so key creation and revocation become config file edits and service restarts. For a single user that is fine and arguably simpler. For a group where people join and leave, the API is the whole point, and rebuilding it yourself means writing the management layer that this repository already provides.

A second alternative is the Outline Manager path the README itself recommends for users who want a graphical interface. That trades control for convenience: you get a UI and a managed workflow, and you give up the direct, scriptable access to the server that comes from running this repository yourself. Neither option is strictly better; the deciding question is whether you want to operate the endpoint or just use it.

## Maintenance cost, release cadence and the Apache-2.0 licence

The upgrade story is the part to plan for. Releases are tagged with a server- prefix, and the newest three are server-v1.12.1 on 2025-02-19, server-v1.12.2 on 2025-02-21 and server-v1.12.3 on 2025-02-24. That clustering suggests fixes can arrive quickly after a tag, which cuts both ways: you get corrections fast, and you may need to upgrade more than once in a short window. The README documents no migration procedure between versions and no rollback, so the practical cost of upgrading is whatever your own host backup and restore process costs.

The repository is licensed Apache-2.0, and the LICENSE file sits at the top level. Apache-2.0 is a permissive licence that includes an explicit patent grant and requires that notices and the licence text be preserved in redistributions. If you fork the server or ship it inside a product, that notice obligation and any NOTICE file handling are the items to read for yourself; this is a description of the licence, not legal advice.

Dependency maintenance is the other recurring cost. package.json pins the toolchain loosely with caret ranges across eslint, prettier, TypeScript and jasmine, while engines.node is fixed at 18.x.x. Those two choices pull in opposite directions: the linters and test runner can drift forward on their own, but the Node major version cannot without a change to package.json. Budget for a periodic npm install against the lockfile to see what has moved.

## Conclusion

Adopt Outline Server if you want to run your own Shadowsocks endpoint and manage access keys programmatically rather than through a hosted service; the README's own path is npm install then ./task shadowbox:start, with Node LTS 18.16.0, npm 9.5.1 and Go 1.21 or newer in place first. Do not adopt it if you want a client, a billing layer or a managed control plane, since the server component is none of those and the Outline Manager is a separate repository. Before committing, verify that the REST API surface described in src/shadowbox/README.md covers the key lifecycle you need, and check the release page, where the newest entry is server-v1.12.3 from 2025-02-24, against the commits on master before you pin a version.

## FAQ

### What is Outline Server?

It is the server component of Outline, developed by Jigsaw, that provides a Shadowsocks service through outline-ss-server and exposes a REST API for access key management. The repository also contains an optional metrics server for anonymous metrics sharing.

### How do I install Outline Server on Ubuntu?

The README lists Node LTS 18.16.0, npm 9.5.1 and Go 1.21+ as prerequisites, then shows npm install followed by ./task shadowbox:start. The postinstall script builds the Go task runner, so Go must be on PATH before npm install runs.

### How do I set up Outline Server?

After installing dependencies, the README's setup step is ./task shadowbox:start, which brings up the core proxy server and its management API. The top-level README defers configuration and usage options to src/shadowbox/README.md.

### Is Outline VPN free to use?

The repository does not describe pricing. Outline Server is distributed as source under the Apache-2.0 licence, and running it yourself means paying for whatever host you deploy it on.

### Who owns Outline VPN?

The repository description attributes Outline Server to Jigsaw. The README also links to an Outline Manager in a separate repository for users who want a graphical interface.

### How do I get an Outline VPN access key on my Android device?

The README does not cover client-side key retrieval. It describes the server's REST API for access key management and points users who want a graphical interface at the Outline Manager, which lives in a separate repository.

## Sources

- [License: Apache-2.0](https://github.com/OutlineFoundation/outline-server/blob/master/LICENSE)
- [OutlineFoundation/outline-server on GitHub](https://github.com/OutlineFoundation/outline-server)
- [Project website](https://getoutline.org/)
- [README](https://github.com/OutlineFoundation/outline-server/blob/master/README.md)
- [Releases](https://github.com/OutlineFoundation/outline-server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/outlinefoundation-outline-server