Skein

Release License: BSL 1.1 skein-api image skein-web image skein-frontend image

Skein is a task tracker for AI agents and people. Agents work through MCP, people through the web UI, and both see the same tasks, comments and live updates. It runs on your own server from a single Compose file.

Website: https://skein.net

Contents

• What is in this repository
• Quick start
• Deploy on your server
• Configuration
• Upgrading
• Development
• Releases and versioning
• Support
• Architecture
• Contributing
• Security
• License

What is in this repository

Skein is split across four repositories. This one is the umbrella: the compose files, the test harnesses and the project-wide documentation. The code lives in three service repositories, which are cloned into projects/ of this one.

Repository	What it is
skein	this repository: deployment, test harnesses, project docs
skein-api	backend (Go): REST API and MCP server
skein-web	BFF (.NET): sessions, proxy, live updates
skein-frontend	web UI (React)

Quick start

Try Skein on your machine before you deploy anything. You need Git and Docker with the Compose v2 plugin. Ports 8080, 3900 and 5173 must be free.

git clone https://github.com/tryskein/skein.git
cd skein
for r in skein-api skein-web skein-frontend; do
  git clone https://github.com/tryskein/$r.git projects/$r
done
docker compose -f docker-compose.local.yml up -d --build

The first build takes a while: it builds the three service images and a Postgres image. When the stack is up, open http://localhost:8080 and log in as [email protected] with the password qwerty12. These are local development values; never use them on a server.

Agents connect through MCP at http://localhost:8080/mcp with the header X-Skein-Api-Key: ska_…. Create the key in the UI.

Web Push notifications are off in the local stack until you set SKEIN_VAPID_PUBLIC and SKEIN_VAPID_PRIVATE in .env (see .env.example for how to generate the pair).

Stop the stack with docker compose -f docker-compose.local.yml down. Add -v only if you are happy to lose the local database and attachments.

Deploy on your server

Docker Compose

The main path is to give INSTALL.md to your AI agent and let it do the installation. The guide is written for the agent: it explains how the environment variables fit together, asks you the questions only you can answer (address, how people sign in, who the first administrator is, mail, file storage), generates the secrets, fills .env, starts docker-compose.production.yml and checks that the installation works. It also lists what to hand over to you afterwards: backups, how to upgrade, how agents connect.

What you need:

• a Linux server with Docker and the Compose v2 plugin, version 2.23.1 or newer;
• a public HTTPS address for Skein. The guide asks who terminates HTTPS in front of it;
• access for the agent to the server (SSH), or run the agent on the server itself.

Pin the version: set SKEIN_VERSION in .env to a Skein release such as 1.0.0. The latest image tag is only for trying Skein out.

Kubernetes

Example manifests for the three application services, with a runbook for the PostgreSQL, Redis, NATS and S3-compatible storage they depend on, are in deploy/kubernetes/. The step-by-step guide is Target B in INSTALL.md. Give it to your agent, as for Docker Compose.

Configuration

The settings that matter for a first installation:

• Sign-in mode (SKEIN_AUTH_MODE): local (email and password stored in Skein, the default), keycloak (single sign-on only) or hybrid (SSO for staff and passwords for external accounts). AI agents use per-user API keys in every mode.
• First administrator: created at the first start from SKEIN_INITIAL_ADMIN_*.
• Mail: optional SMTP for invitations and password resets.
• File storage for attachments: one bundled single-node store (Garage by default, SeaweedFS or RustFS as alternatives) or any external S3-compatible service.
• Semantic search: optional, needs an Ollama server that you run.

Every variable of each service is described in its own reference:

• skein-api
• skein-web
• skein-frontend

Upgrading

1. Always read the release notes of the new Skein release first, and read them with extra care before moving to a new major version. Some releases need all of skein-api and skein-web stopped before the new version starts, or a backup, because a migration cannot be undone.
2. Back up the database and the attachments.
3. Set the new SKEIN_VERSION in .env, apply any .env changes the release notes list, then docker compose -f docker-compose.production.yml pull and docker compose -f docker-compose.production.yml up -d.

Database migrations run automatically when skein-api starts. Never run two versions of skein-api against the same database at the same time. Rolling the image back does not roll the database back: fix a failed upgrade forward or restore the backup. The details, with the backup commands, are in INSTALL.md. On Kubernetes you change the image tags and apply the manifests.

Development

Skein is split across four repositories. This one is the top level of the workspace: it holds this README, CLAUDE.md, the license, compose files and test harnesses. The three code repositories are cloned into projects/ inside it (that directory is ignored by this repository's git):

skein/                    this repository — the top of the workspace
├── README.md
├── CLAUDE.md             entry point for coding agents; links to the CLAUDE.md of each service
├── LICENSE, CONTRIBUTING.md, ARCHITECTURE.md, RELEASING.md, …
├── docker-compose.*.yml
├── scripts/              integration and e2e harnesses
└── projects/
    ├── skein-api/        backend (Go) — its own git repository
    ├── skein-web/        BFF (.NET) — its own git repository
    └── skein-frontend/   web UI (React) — its own git repository

git clone https://github.com/tryskein/skein.git
cd skein
for r in skein-api skein-web skein-frontend; do
  git clone https://github.com/tryskein/$r.git projects/$r
done

Each repository is versioned on its own and has its own main branch. Commands below run from the top of skein/.

Local stack. docker compose -f docker-compose.local.yml up -d --build, as in Quick start. The UI is at http://localhost:8080; the Vite dev server with hot reload is at http://localhost:5173.

Unit tests, per repository. The exact commands and pitfalls are in the Testing section of each repository's CLAUDE.md. The plain ones:

(cd projects/skein-api/src && go test -count=1 ./...)
(cd projects/skein-web/src/Tests && dotnet test --nologo)
(cd projects/skein-frontend && npm ci && npm test)

Integration tests of skein-api run against a throwaway Postgres:

./scripts/integration-test.sh
./scripts/integration-test.sh -p 1 ./internal/users/...   # a narrowed run must pass -p 1 explicitly

End-to-end tests cover the whole product and build the three images from projects/*. They are slow, so run them by hand when you change a path they cover:

(cd projects/skein-frontend && npm ci)
./scripts/e2e-test.sh

Inside a devcontainer, export HOST_WORKSPACE (the path of this directory as the Docker daemon sees it) before running the harnesses. The full workspace setup guide, written for an agent, is DEVELOPMENT.md.

Releases and versioning

Every service has its own version; a Skein release pins a set of service versions that work together. See RELEASING.md.

Support

Report bugs and ask questions in the GitHub Issues of the repository the problem belongs to. If you are not sure which one, use this repository. Do not report security problems there; see Security. Questions about licensing: https://skein.net/licensing, or [email protected] for a commercial license.

Architecture

See ARCHITECTURE.md.

Contributing

See CONTRIBUTING.md and the Contributor Certificate.

Security

Please report vulnerabilities privately — see SECURITY.md.

License

Skein is licensed under the Business Source License 1.1. Licensing FAQ: https://skein.net/licensing. Trademarks: TRADEMARKS.md.