F R I D A Y

F.R.I.D.A.Y

The secure self-improving personal AI agent — local-first, self-hosted, with persistent memory, tools, voice, MCP, automation, and verified self-extension.

Built to work for you. Built to get better.

Quick start · Capabilities · Architecture · Channels · Recovery · Development · Roadmap · Contribute

---

Meet F.R.I.D.A.Y

The current product direction and staged implementation plan are documented in the [F.R.I.D.A.Y roadmap](docs/ROADMAP.md), with system boundaries in the [platform architecture](docs/ARCHITECTURE.md). Desktop and Android applications begin after the shared client protocol, persistent Agent, Project, Computer Node, Routine, Review Policy, and Search foundations are implemented. Gateway deployment and pairing operations are documented in [CLIENTGATEWAY.md](docs/CLIENTGATEWAY.md).

F.R.I.D.A.Y is a local-first, self-hosted personal AI agent designed to behave less like a one-shot chatbot and more like a long-lived assistant that stays useful across projects, devices, sessions, and restarts.

It combines a plugin-first agent runtime with durable sessions and background jobs, persistent memory, scheduling, multi-channel messaging, secure tool execution, MCP integrations, encrypted secrets, observability, and a verified self-improvement/restart path.

The self-improvement path is reuse-first: F.R.I.D.A.Y inspects existing tools, actions, typed plugin capabilities, contribution instances, and MCP options before deciding new code is necessary. When code is required, changes are isolated, evaluated, verified, promoted, and handed off through explicit lifecycle boundaries instead of treating the running system as an unrestricted rewrite target.

You can talk to the same agent from a configured messaging channel, give it work that takes time, continue doing something else, come back later, schedule future work in your own timezone, or ask it to extend a missing capability when the runtime can safely build and verify one.

> [!IMPORTANT] > F.R.I.D.A.Y can execute code, invoke tools, communicate with external services, and mutate files when permitted. Treat it like powerful local automation software: review permissions, use sandboxing where appropriate, protect credentials, and do not expose trusted channels to untrusted users.

Why F.R.I.D.A.Y is different

• Self-improving, not self-rewriting by default. Reuse and capability discovery come first; verified self-extension is a bounded fallback when an explicitly requested capability is actually missing.
• Plugin-native and machine-discoverable. Typed capabilities, contributions, hooks, and concrete contribution instances are discoverable from the real plugin contracts/registrations rather than a manually maintained feature catalog.
• Local-first and self-hosted. Runtime state, durable sessions, memory, tools, and operator controls live under your installation rather than requiring a hosted assistant service.
• Security is part of the architecture. Vault, permissions, sandboxing, trusted channel principals, typed authority boundaries, verification, rollback, and authenticated lifecycle handoff are designed into the runtime.

What F.R.I.D.A.Y can do

| Capability | What it means | | --- | --- | | Personal assistant | Maintains useful context across conversations, sessions, projects, and durable memory. | | Long-running work | Runs persistent session jobs without forcing one conversation to wait for another task. | | Coding and automation | Uses execution tools, files, processes, sandboxes, integrations, and model-driven workflows. | | Multi-channel access | Receives and replies through Telegram, Discord, Slack, WhatsApp, Signal, Email, Teams, Google Chat, and SMS/Twilio. | | Voice | Optional speech-to-text and text-to-speech through OpenAI, Deepgram STT, or ElevenLabs TTS; audio transcripts enter the same Turn Loop as text while remaining explicitly untrusted user content. | | Conditional hooks | Persists user-scoped conditions/instructions for turn, action, or handover phases with bounded invocation counts. | | Scheduling | Stores durable one-shot and recurring schedules in the user's configured IANA timezone. | | Memory | Keeps bounded preferences, habits, and graph-like relationships without stuffing the full history into every prompt. | | Skills | Installs and creates reusable skills that can be surfaced to the agent when relevant. | | MCP and integrations | Connects external tools and services through permission-gated capability boundaries. | | Secure secrets | Stores credentials in an encrypted Vault instead of plaintext runtime configuration. | | Sandboxed execution | Uses a pluggable sandbox-provider contract; kern is the built-in default, while other providers can be registered without changing tools or execution policy. | | Crash recovery | Writes secret-redacted crash records and supports supervised automatic restart. | | Self-extension | Can feasibility-check, build, evaluate, promote, restart, and resume after adding a missing software capability. |

What "self-extension" means

F.R.I.D.A.Y does not blindly rewrite itself after every conversation. When an explicitly requested capability is missing, the self-improvement path can:

1. inspect installed actions/tools and capability contracts before choosing new code;
2. for external/tool integrations, search configured MCP servers and the official MCP Registry, then accept MCP only after a live tool description/input-schema check verifies the exact requested operation;
3. determine whether any genuinely missing capability is feasible and choose the owning code placement only after MCP-first discovery finds no exact live match;
4. request explicit authorization before making code changes;
5. create changes in an isolated worktree only when code is actually required;
6. run quality/evaluation gates;
7. promote a verified generation;
8. perform an authenticated two-process handoff; and
9. resume the original request after the successor is ready.

When an existing action, tool, or typed capability already solves the request—or an MCP candidate has been live-verified for the exact operation—F.R.I.D.A.Y avoids the code-generation/restart path. Registry names/descriptions alone are never treated as proof that an MCP can do the job.

If other foreground turns or background jobs are active at restart time, F.R.I.D.A.Y asks before pausing them and explains the recovery boundary.

Quick start

Install the latest release

On Linux or macOS:

tmp="$(mktemp)"
curl --proto '=https' --tlsv1.2 -fsSL \
  https://github.com/saravanaspar/F.R.I.D.A.Y/releases/latest/download/install-release.sh \
  -o "$tmp"
gh attestation verify "$tmp" \
  --repo saravanaspar/F.R.I.D.A.Y \
  --cert-identity https://github.com/saravanaspar/F.R.I.D.A.Y/.github/workflows/release.yml@refs/heads/main \
  --source-ref refs/heads/main \
  --deny-self-hosted-runners
sh "$tmp" saravanaspar/F.R.I.D.A.Y
rm -f "$tmp"

The bootstrap installer is itself an attested GitHub Release asset; do not execute the mutable copy from main. The installer supports Linux and macOS on x64/arm64, verifies the matching binary's SHA-256 checksum and GitHub build-provenance attestation, preflights the candidate locally, and atomically installs friday into ~/.local/bin by default. A recent GitHub CLI (gh) with gh attestation verify support is required and installation fails closed if provenance cannot be verified.

Then run:

friday setup
friday

Setup creates a dedicated writable workspace at ~/FRIDAY-workspace by default and persists it as FRIDAY_WORKSPACE. Protected state remains under ~/.friday; do not use $HOME, ~/.friday, or a parent of protected state as the model/tool workspace.

On Windows, the supported path is WSL2 rather than an unsafe native build. From PowerShell, download and run the WSL installer wrapper:

$installer = Join-Path $env:TEMP "friday-install.ps1"
Invoke-WebRequest https://github.com/saravanaspar/F.R.I.D.A.Y/releases/latest/download/install-release.ps1 -OutFile $installer
gh attestation verify $installer --repo saravanaspar/F.R.I.D.A.Y --cert-identity https://github.com/saravanaspar/F.R.I.D.A.Y/.github/workflows/release.yml@refs/heads/main --source-ref refs/heads/main --deny-self-hosted-runners
& $installer
Remove-Item $installer -Force

That installs the hardened Linux binary inside your default WSL2 distribution. Enter WSL2 and run friday setup, or invoke it from PowerShell with wsl sh -lc '$HOME/.local/bin/friday setup'.

> [!NOTE] > The release installer requires a published GitHub Release for the requested platform. Native Windows release binaries are intentionally not published yet: F.R.I.D.A.Y relies on POSIX private-file permissions in security-sensitive state paths. The PowerShell installer uses WSL2 so those guarantees remain intact until equivalent native Windows ACL enforcement and tests exist.

Build from source

Requirements:

> On a Windows host, build and run F.R.I.D.A.Y inside WSL2. Native Windows execution is not yet a supported hardened security boundary.

• Node.js 22.22.2 and npm for the release-equivalent toolchain (.node-version pins this exact build runtime);
• Git;
• at least one supported ingress channel and one explicitly confirmed exact operator identity during first-run setup;
• credentials for the model provider you select, when required.

git clone https://github.com/saravanaspar/F.R.I.D.A.Y.git
cd F.R.I.D.A.Y
npm ci
npm run friday -- setup
npm run friday

To build the standalone executable for the current host:

npm ci
npm run build:binary
./build/binary/friday setup
./build/binary/friday

First-run setup

The normal installed flow is intentionally small:

friday setup
friday

On the first setup, F.R.I.D.A.Y asks for Quick setup or Custom setup. Existing/local onboarding is not removed. Both modes begin with the same mandatory local security block:

1. a routing/system model and its credential when required;
2. at least one enabled ingress channel with one explicitly confirmed exact operator identity;
3. an explicit host privilege policy: restricted approved-operation broker or no privileged operations.

A main reasoning model is no longer mandatory during bootstrap. In router-only mode, typed setup/admin actions continue to work while general reasoning requests explain that a main model still needs to be configured. Quick setup stops after the mandatory block so you can start F.R.I.D.A.Y and send continue setup from the paired trusted channel. Custom setup keeps the mandatory block first, then offers the existing terminal model/runtime/Voice/sandbox/Python/self-improvement setup areas as optional/skippable steps. Anything skipped can still be configured later locally or from the trusted channel.

Runtime defaults are not published until the routing model and first exact operator pairing are complete. allowAll may widen transport admission, but it never creates an operator implicitly. The host privilege policy is independent from Agent permission mode: full Agent permission still cannot sudo when host privilege mode is none. Broker mode never grants an arbitrary root shell; sudo authentication/installation happens only in the local terminal, and remote operations use only the fixed root-owned helper with sudo -n. Secrets are never written to runtime.env.

After bootstrap, a trusted channel can continue onboarding and administration with typed actions for the main/routing models, permissions/timezone, additional channels, Voice, sandbox, execution Python, MCP, Skills, self-improvement source, Doctor and diagnostics. Channel diagnostics.doctor runs the same canonical check set as local friday doctor; only the presentation differs. onboarding.main-model.setup is conversational: it can ask for provider/model choices and, when needed, choose API-key or supported OAuth authentication. API-key input and OAuth code/redirect prompts use protected channel interactions, and resulting credentials go directly to Vault instead of through ordinary router/main-model text. Successful Voice, execution-Python, sandbox, MCP and Skills operations advance the resumable onboarding state automatically.

Useful setup commands:

friday setup
friday setup --timezone Asia/Kolkata
friday setup sandbox
friday setup execution-python
friday setup self-repository /path/to/F.R.I.D.A.Y
friday setup whatsapp
friday setup voice
friday setup privileges broker
friday setup privileges none
friday setup --help

MCP servers, skills, personas, and other plugin-owned capabilities are normally managed conversationally through a trusted configured channel.

Optional host capabilities

The core assistant does not silently install privileged host software. Enable only the capabilities you need:

| Capability | Host requirement | Notes | | --- | --- | --- | | Private execution Python | uv or Python 3.11 | Provision with friday setup execution-python; the environment pins the kernel dependencies exactly. | | Coding sandbox | Configured SandboxProvider (kern built in) | Install the selected provider, then run friday setup sandbox; see [docs/SANDBOX.md](docs/SANDBOX.md). Sandbox internet is blocked by default and network-bearing commands require an explicit request/permission approval. | | Self-improvement from source | Git + npm + a clean F.R.I.D.A.Y checkout | Save the canonical checkout with friday setup self-repository /path/to/F.R.I.D.A.Y. Release-binary self-improvement builds, verifies, stages, and hands off to a new host-native binary before activation. | | WhatsApp bridge | npm/Node tooling | Provision bridge dependencies with friday setup whatsapp. | | Voice | Provider API access | Configure and preflight STT/TTS with friday setup voice. OpenAI reuses the canonical model-provider Vault credential; Deepgram and ElevenLabs keys are stored in Voice-owned Vault refs. |

Run friday doctor at any time for a sectioned installation, configuration, security, tooling, and recovery report. Every actionable warning/error includes a one-line repair guide. Doctor is non-interactive by default, does not make outbound network calls, and never reads plaintext Vault secrets. Use friday doctor --fix only when you want guided, confirmed repairs for deterministic fixes, or friday doctor --json for machine-readable diagnostics.

Channels

F.R.I.D.A.Y routes human messaging through a common trusted channel boundary while keeping provider-specific transport logic isolated.

| Channel | Ingress | Egress | Approval UI | Media ingress | | --- | :---: | :---: | --- | --- | | Telegram | Yes | Yes | Native buttons + text code | Retrieved | | Discord | Yes | Yes | Native buttons + text code | Retrieved | | Slack | Yes | Yes | Native buttons + text code | Safe notice only | | WhatsApp | Yes | Yes | Text code | Safe notice only | | Signal | Yes | Yes | Text code | Safe notice only | | Email | Yes | Yes | Text code | Safe notice only | | Microsoft Teams | Yes | Yes | Adaptive Card buttons + text code | Safe notice only | | Google Chat | Yes | Yes | Card buttons + text code | Safe notice only | | SMS / Twilio | Yes | Yes | Text code | Safe notice only |

Network channels default toward explicit identity/access configuration. Protected approvals, credential capture, trusted prompts, and cancellation codes are intercepted before ordinary routing/model use and scoped to the exact channel/account/conversation/sender/thread principal. Protected state is persisted privately so a restart rejects stale replies and callback replays instead of routing them as new user requests. Unsupported media is admitted as an explicit safe notice with no unusable attachment handle.

Email identity is derived from the parsed From address;

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: saravanaspar
• Source: saravanaspar/F.R.I.D.A.Y
• License: MIT

Install and usage instructions live in the source repository linked above.