Sally Docs

Implementation-backed docs for installing, operating, and integrating Sally.

Installer

Overview

Sally is installed and updated through create-sally. This is the official operator entrypoint for fresh installs, guided updates, and deployment checks.

npx --yes create-sally@latest

npx --yes create-sally@latest update

npx --yes create-sally@latest doctor --dir /opt/sally-instance

Install Sally

The normal install path for a fresh Ubuntu or Debian box is the interactive installer.

Node.js must be installed first, because create-sally runs through npx.

ssh root@your-server-ip

apt update && apt install -y curl ca-certificates gnupg && \
mkdir -p /etc/apt/keyrings && \
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && \
apt update && apt install -y nodejs

node -v
npm -v
npx -v

npx --yes create-sally@latest

Recommended default: managed-simple.

Install Modes

managed-simple is the default path. It sets up Docker, Postgres, HTTPS via Caddy, and the Sally web + API containers.

existing-infra is for setups that already have reverse proxy, TLS, or other infrastructure decisions in place.

npx --yes create-sally@latest install \
  --mode managed-simple \
  --dir /opt/sally-instance \
  --domain sally.example.com \
  --workspace Operations \
  --superadmin-email owner@example.com \
  --superadmin-name "Sally Admin" \
  --acme-email owner@example.com \
  --email-setup later \
  --version latest \
  --yes

Update Sally

The updater is designed for deployments originally created by create-sally.

npx --yes create-sally@latest update

npx --yes create-sally@latest update --dir /opt/sally-instance --version latest --yes

It updates managed image references, pulls fresh images, applies schema changes, reruns bootstrap safely, restarts services, and verifies health.

Doctor & Checks

doctor is the quick health/config check path for installer-managed deployments.

npx --yes create-sally@latest doctor --dir /opt/sally-instance

It checks Docker, Docker Compose, install structure, detected mode/version, and lightweight health checks.

Recovery

The core recovery model is database dump + uploads backup + restore verification.

sudo /opt/sally/ops/backup.sh

curl -sS https://your-sally-domain.com/api/health

Operators should test restore procedures before they need them in production.

API

Overview

Sally has a real HTTP API behind the web app. It is the implementation-backed source of truth for workspaces, projects, tasks, clients, notifications, timesheets, API keys, and hosted MCP keys.

Expected API variables

YOUR_SALLY_DOMAIN — your deployed Sally base domain, for example app.example.com
YOUR_API_KEY — a personal Sally API key with the atpm_... prefix
YOUR_WORKSPACE_SLUG — workspace slug when the caller belongs to multiple workspaces

Typical base paths

https://YOUR_SALLY_DOMAIN/api for deployed environments
http://127.0.0.1:4000 for local API development

Auth & Workspace Selection

Sally supports session auth, personal API keys, hosted MCP keys, and an optional global API token for bootstrap/testing scenarios.

Available auth inputs

Authorization: Bearer <sessionToken>
Authorization: Bearer <apiKey>
Authorization: Bearer <mcpKey> for hosted MCP
X-Session-Token and X-Api-Key as compatibility headers where supported

Workspace selectors

X-Workspace-Id
X-Workspace-Slug
query params like workspaceId, workspaceSlug, workspace_id, and workspace_slug

For most non-auth routes, workspace selection should be explicit through X-Workspace-Id or X-Workspace-Slug.

Projects & Tasks

Projects and tasks are the operational core of Sally.

Expected project/task fields

projectId — required for task creation
title — required for task creation
statusId — preferred when exact status targeting matters
status — supported by name when exact id is not used
labels, todos, dueDate, priority, description — optional task fields

Available behavior

project creation auto-creates default statuses
task assignment can create assignment notifications
comments can create mention notifications
inline task-description images are supported

Timesheets & Reporting

Sally supports project and task timesheets plus workspace-wide reporting, with permission-aware visibility and edit rules.

Expected report/query variables

from and to dates
optional projectId, clientId, taskId, userId
optional showValidated=true

Available write fields

minutes
date
description
billable
validated when the caller has sufficient permission

Tutorials

Use the API for practical end-to-end flows like listing projects, creating tasks, inviting members, creating hosted MCP keys, and generating reports.

Good integration habits

treat workspace selection as explicit when the user belongs to multiple workspaces
prefer ids over names once discovered
fetch statuses first if exact status writes matter
revoke temporary test keys after experiments

Architecture

Sally is a TypeScript-first system with a web app for humans, an HTTP API for integrations, and MCP interfaces for agent tooling.

The monorepo includes apps/web, apps/api, apps/create-sally, and apps/mcp.

MCP

Overview

Sally supports two MCP patterns: hosted MCP at /mcp and local stdio MCP via sally-mcp. Hosted MCP is the primary path.

Hosted MCP Quickstart

curl -X POST https://your-sally-domain.com/mcp \
  -H 'Authorization: Bearer sallymcp_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data @initialize.json

Normal flow: create hosted MCP key, point client at /mcp, authenticate, initialize, list tools, call tools.

Local stdio MCP

sally-mcp is the advanced or legacy local wrapper path.

SALLY_URL=https://your-sally-domain.com \
SALLY_USER_API_KEY=atpm_... \
sally-mcp

Concepts

Sally is API-first, designed for humans + agents, low-noise UI, and a self-hostable operational core rather than collaboration theater.

End-User Usage

Overview

Sally is a project management system for teams that want a clean operational surface instead of a bloated collaboration suite.

Workspaces & Projects

Workspaces are the top-level collaboration boundary. Projects are the main execution container inside them.

Tasks & Timesheets

Tasks are the unit of execution. Timesheets record the work done against projects and tasks.

Keys & Notifications

Sally supports personal API keys, hosted MCP keys, task assignment notifications, comment mention notifications, and per-event notification preferences.

Licensing

Sally is source-available under BSL 1.1 with an Additional Use Grant. Self-use is allowed; SaaS, white-labeling, and third-party hosting require separate rights.