English | 简体中文

A management center for a fleet of Scoot agents.

Scoot is a local-first, single-binary AI agent that runs on your machines and keeps every action in a JSONL audit trail. Today each Scoot install is an island. scootship is the management center that the Scoot project's docs/EDGE.md points to: a single Go binary that ingests append-only fleet telemetry over the scoot-edge protocol and serves an embedded admin dashboard so you can observe the whole fleet from one place.

Status: Phase 2 center-side dispatch core (pre-1.0). The center ingests status heartbeats and audit_batch log shipping and renders the fleet. Task dispatch/orchestration (EDGE.md E2) now has a persisted center-side queue, node-bound lease output, lifecycle ingestion, and idempotency/provenance tests. Dashboard operators holding the dispatch:manage capability can create new node-targeted dispatch jobs; the /dispatch list itself remains a read-only audit view, and job control (cancel/retry) is not yet built. See docs/roadmap.md for the project shape, boundaries, and direction.

scoot-edge is, by design, an optional companion that dials out to a center; the edge never opens a listener. That makes the center the only inbound trusted surface in the fleet, so scootship is built defensively:

• Every node endpoint is authenticated by a per-node bearer token, and the dashboard by a login session (form login + HttpOnly cookie, not the browser's basic-auth popup).
• The dashboard login is rate-limited per source IP: repeated failures lock that IP out for a cooldown (with a Retry-After), so the center's sole inbound surface resists brute force.
• Every response carries defensive headers (a strict Content-Security-Policy with no inline scripts, plus X-Frame-Options, X-Content-Type-Options, and Referrer-Policy).
• Telemetry is append-only and is never reflected back into a node's local state.
• The center can never raise a node's local policy ceiling — it isn't a permission console.

One honest caveat from EDGE.md carries over: once a node opts in to audit shipping, the bodies it ships (file contents, command output) live at the center. Treat the center, and its dashboard login, as sensitive. The dashboard/API keep a bounded recent audit window per node and mark an explicit audit_gap when that window trims; accepted audit batches are still persisted append-only to the center JSONL log.

        Operators (browser · login session)
                 |
                 v
   +-------------------------------------------+
   |        scootship (single Go binary)        |
   |  embedded dashboard (embed.FS)             |
   |  POST /telemetry   GET /jobs/lease (E2)    |
   |  per-node token auth · append-only store   |
   +----------------------^---------------------+
                          |  edge dials OUT (HTTPS + per-node token)
        +-----------------+-----------------+
        |                 |                 |
    scoot-edge        scoot-edge        scoot-edge   (optional companion)
        |                 |                 |
      scoot             scoot             scoot

Requires Go 1.26+. No external dependencies, no Node toolchain, no database to install — the dashboard and storage are built in.

# Terminal 1 — run the center in dev mode (dashboard open, demo token n-dev=dev-token seeded)
SCOOTSHIP_DEV=1 go run ./cmd/scootship serve

# Terminal 2 — drive the heartbeat -> ingest -> dashboard path with the built-in simulator:
go run ./cmd/scootship mock-edge -ship-audit

Open http://localhost:8080. You'll be redirected to a sign-in page — in dev mode log in with admin / admin. After signing in you get the dashboard shell with a collapsible left sidebar (Fleet, Dispatch, Tokens, Operators + a Settings menu with Account), plus top-right sign-out: the n-dev node goes online, with its policy ceiling, derived audit counts, capability labels, and (because -ship-audit is on) a few ingested audit events on the node detail page.

Or use the Makefile:

make run         # center in dev mode
make mock-edge   # simulated node
make docs        # build bilingual mdBook docs into ./book (requires mdBook)
make docs-serve  # preview the English mdBook root locally
make ci          # fmt-check + vet + test + build

• CI runs on pushes, pull requests, and manual dispatch via .github/workflows/ci.yml: gofmt, go vet, go test, go build, a CLI version smoke, and release-target cross-compile smoke checks.
• The docs workflow in .github/workflows/docs.yml builds the bilingual mdBook on docs-related pushes, pull requests, and manual dispatch; pushes to main also deploy the generated book/ site to GitHub Pages.
• Pushing a vX.Y.Z tag triggers .github/workflows/release.yml, which injects the tag into internal/version.Version, cross-compiles single-binary archives for Linux, macOS, and Windows, publishes checksums with the GitHub release, and publishes multi-arch Linux Docker images to GHCR as ghcr.io/scootship/scootship:X.Y.Z plus latest tags.
• Project-local agent skills live in .agents/skills: auto-release for controlled release orchestration and project-audit for scored whole-repo health reports.

serve is configured from the environment (secrets never come from committed config):

mock-edge is a dev/test client configured by flags: -center, -node, -token, -interval, -ship-audit. It sends the token as Authorization: Bearer <token> and the envelope node_id must match the node assigned to that token.

The dashboard can also create, rotate, and revoke center-managed node tokens. The center generates high-entropy bearer token secrets, displays them once after creation or rotation, never lists or returns them from inventory APIs, and persists them in SCOOTSHIP_DATA_DIR/managed_node_tokens.json with private 0600 permissions. Revocations are stored there too, so an operator can revoke a token originally loaded from the env or private token file without editing that original source. Configure a real scoot-edge with the same node id and secret; in the current edge client flow that means setting SCOOT_EDGE_TOKEN=<secret> and using --node-id <node> against the center's /telemetry endpoint.

For production setup, data-directory permissions, TLS proxy boundaries, backup, and restore, use the operator runbook in docs/deployment.md.

scootship implements the center side of the frozen scoot-edge v1 contract. The wire shapes live in internal/protocol and mirror EDGE.md exactly:

• Envelope {"v":1,"type":"status|audit_batch|job|job_event","node_id":"...","sent_ts":...,"body":{}}.
• E1 (implemented): POST /telemetry accepts status and audit_batch (and forward-compatibly job_event). Audit ingest is idempotent on the {file_gen, byte_to} cursor and acks the durably stored cursor so the edge only advances after a durable ack. Telemetry batches are decoded and validated before store mutation; invalid audit cursors, empty audit batches, and unknown audit event kinds are rejected. The recent audit window is bounded by SCOOTSHIP_AUDIT_RETENTION_EVENTS; trimming is visible as a center-side audit_gap. Node detail API/pages also group retained audit by session_id / run_id into chronological run timelines.
• E1 health signals (implemented): fleet and node pages derive read-only signals for stale nodes, version drift, audit body lag, retention gaps, duplicate audit reports, policy denies, system errors, and unrestricted local ceilings. They do not trigger remediation or mutate node state.
• Node token lifecycle (implemented): dashboard operators can create, rotate, and revoke center-managed per-node authentication tokens; secrets are generated by the center, displayed once, and then never listed, returned by APIs, logged, or audited.
• Dashboard action authorization (implemented): authenticated operators carry direct built-in capabilities (fleet:view, tokens:manage, operators:manage) instead of role groups. All authenticated state-changing forms require a session-bound CSRF token.
• E2 center-side core (implemented): GET /jobs/lease authenticates the node, requires a matching node query param, bounds capacity, and returns only jobs already persisted for that node. Dispatch records are append-only JSONL snapshots with idem_key de-duplication, node binding, capability/label miss rejection (no_matching_capability), only-lower policy clamping against the node's reported ceiling, and lifecycle updates from validated job_event telemetry. Dashboard operators holding the dispatch:manage capability can create a new node-targeted job from /dispatch/new (session + CSRF protected, bounded by a configurable per-node pending-job queue cap); the /dispatch list and JSON API remain a read-only audit view, and there is still no cancel/retry/edit control surface for an existing job.

scootship talks only this contract; it does not depend on any Scoot internal.

Read AGENT.md (engineering handbook) and docs/roadmap.md (intent and hard boundaries) before making changes. For production operation, read docs/deployment.md. Run make ci before pushing.

MIT — matching the Scoot ecosystem.