Skip to content

getting-started.md

Latest commit

 

History

History
198 lines (138 loc) · 5.03 KB

getting-started.md

File metadata and controls

198 lines (138 loc) · 5.03 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

Option A - npm package

npm install -g @thesongzhu/friday
friday start

Open:

http://localhost:3141

Option B - source checkout

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

Open:

http://localhost:3141

Option C - Docker from source

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

Open:

http://localhost:3141

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, QQ, or webhooks only when you want that surface and can verify it.
  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.0"
  }
}

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.