Skip to content

getting-started.md

Latest commit

 

History

History
223 lines (159 loc) · 6.68 KB

getting-started.md

File metadata and controls

223 lines (159 loc) · 6.68 KB
Raw

Getting Started With Friday

This guide gets Friday running locally, completes setup, and explains what to do when a capability is missing.

Friday is local-first and BYOK. You can start it without every provider configured, but real tasks that need models, search, OCR, TTS, optional channels, or third-party accounts require valid credentials and verification.

Prerequisites

  • Node.js 22+
  • npm 10+
  • Git
  • A modern browser
  • Optional: model/search provider keys, such as OpenAI, Doubao/Volcengine, Tavily, Serper, or other supported providers

Check your local runtime:

node --version
npm --version

Install And Start

npm is a developer / build / tooling surface, not a consumer install path. The npm package is a developer/build/tooling surface for running Friday from source, in CI, and for internal tooling; it is not a consumer install path. npm install does not install the full Friday product: it does not ship a signed/notarized native macOS app, the managed native-app Hub lifecycle, native mobile apps, formal auto-updates, or Endbar release guarantees. The native Friday.app is the consumer release vehicle, and it is not yet publicly released — so there is no "download the official app" step yet. Until then, developers and maintainers run Friday from source (below).

Option A - source checkout (developer path)

git clone https://github.com/thesongzhu/Friday.git
cd Friday
npm install
npm run build
npm start

Open:

http://localhost:3141

Option B - Docker from source (developer path)

docker compose -f docker/docker-compose.yml up --build

Open:

http://localhost:3141

Option C - npm package (developer / tooling only, not a consumer install)

The published @thesongzhu/friday npm package is a developer/tooling runtime. Installing it globally gives you the friday CLI for local development, CI, and internal tooling — not the consumer Friday product.

npm install -g @thesongzhu/friday
friday start

Open:

http://localhost:3141

What the npm package can do today: run a local hub for development via friday start / friday daemon, exercise skills (friday list, friday run), and drive the source build/test pipeline (npm run build, npm test, npm run lint, npm run typecheck) from a source checkout — aimed at developers, maintainers, and CI.

What it cannot do: it is not a signed/notarized native app, provides no managed native-app Hub lifecycle, no native mobile apps, no formal auto-updates, and no Endbar release guarantee. For the consumer experience, wait for the native Friday.app release.

First-Run Setup

Setup should guide you through:

  1. Local session: Friday establishes a local browser session for this machine.
  2. Provider: choose or auto-detect a model provider, enter credentials, and verify the lane.
  3. Capabilities: review text, vision, OCR, embedding, web search, PDF, browser, files, skills, workflows, memory, TTS, and optional channel support.
  4. Channels: connect optional chat/control channels such as Discord, Telegram, Feishu/Lark, Signal, WhatsApp, or webhooks only when you want that surface and can verify it. QQ and Slack HTTP Events-API inbound are explicitly unsupported in the public 1.0.x local-candidate line.
  5. Home: after setup completes, opening Friday should go directly to Home.

If setup cannot verify a capability, it should say what is missing, where to configure it, and how to test it after configuration.

Provider Keys

Friday does not include model or paid search credentials. Bring your own keys.

Common setup paths:

Need Typical provider path What Friday should show if missing
Text model OpenAI, Doubao/Volcengine, Moonshot, Anthropic, Google, OpenRouter missing provider key or invalid route
Vision / multimodal provider with image input support missing vision-capable model or API key
OCR provider OCR API or installed OCR skill missing OCR provider, account, or skill
Web search Tavily, Serper, or custom search skill missing search key or disabled provider
Embedding / memory search embedding-capable provider or local embedding lane missing embedding provider
TTS provider TTS lane or local speech skill missing TTS provider

Missing external accounts, OAuth, payment, CAPTCHA, API keys, and sensitive permissions are human blockers. Friday should not mark those tasks as complete until real verification passes.

Your First Goal

After setup, try a small task that exercises the closure loop:

Summarize what capabilities are configured, list what is missing, and tell me the next setup step.

Friday should answer with:

  • available capabilities
  • missing capabilities
  • exact human blockers
  • configuration path
  • verification step

Auto-Start On macOS

To keep Friday available after login:

bash scripts/ops/install-friday-launchagent.sh

Check status:

bash scripts/ops/friday-launchagent-status.sh

See macOS Auto-Start for logs, uninstall steps, and channel wake behavior.

Development Workflow

From source:

npm run typecheck
npm run lint
npm run build
npm test

npm run typecheck covers source, operator-client, UI, and type-level contracts. It does not replace the normal .test.ts Vitest suite; use npm test for that.

Useful targeted checks:

npm run ops:doctor:runtime
npm run check:security-doctor
npm run check:audit-integrity
npm run check:provider-reliability

Skills And Workflows

Friday can turn repeated work into reusable skills and workflows, but executable capability must stay reviewable.

Common commands:

friday list
friday import ./my-skill.friday.tgz
friday import ./path/to/SKILL.md
friday import https://github.com/example/skill-repo.git

Every generated or imported capability should move through:

candidate -> plan -> sandbox/test -> approval if required -> install/register -> doctor verify -> available

See Extending Friday for authoring guidance.

API Health Check

curl http://localhost:3141/v1/health

Expected shape:

{
  "ok": true,
  "data": {
    "status": "ok",
    "version": "1.0.2"
  }
}

Troubleshooting

Use Troubleshooting when:

  • Friday opens a recovery/auth page instead of Home.
  • setup status is unavailable.
  • a provider shows the wrong name or route.
  • a capability says it is available but the representative task fails.
  • a channel receives messages but cannot control Friday.
  • a generated skill installs but cannot pass verification.

For security-sensitive problems, follow SECURITY.md.