workspace.yml is the configuration file at the root of every Friday space. It defines agents, jobs, signals, memory stores, and MCP server connections. Friday Studio reads this file at startup and applies it live when you save changes.
The annotated example below is drawn from the GitHub Digest starter space — a scheduled job that summarizes open PRs and review requests every Monday and Thursday.
Complete annotated example
# Schema version. Always "1.0".
version: '1.0'
workspace:
name: GitHub Digest
description: Scheduled GitHub PR and review digest every Monday and Thursday
# ---------------------------------------------------------------------------
# Signals — define what triggers your jobs
# ---------------------------------------------------------------------------
signals:
github-digest-schedule:
description: 'Fires every Monday and Thursday at 8:30am Pacific'
provider: schedule # schedule | http | fs-watch | slack | telegram | discord | whatsapp | teams
config:
schedule: '30 8 * * 1,4' # Standard cron expression
timezone: America/Los_Angeles
# ---------------------------------------------------------------------------
# Jobs — define what runs when a signal fires
# ---------------------------------------------------------------------------
jobs:
github-digest-job:
description: 'Every Monday and Thursday: summarize open PRs and review requests'
triggers:
- signal: github-digest-schedule # Must match a key in `signals`
fsm:
initial: idle
states:
idle:
'on':
github-digest-schedule:
target: run
run:
entry:
- type: agent
agentId: github-digest-agent # Must match a key in `agents`
outputTo: digest-result # Saves agent output as a named artifact
- type: emit
event: DONE
'on':
DONE:
target: done
done:
type: final
# ---------------------------------------------------------------------------
# Agents — define the AI components jobs can invoke
# ---------------------------------------------------------------------------
agents:
github-digest-agent:
type: llm # llm | atlas | user | system
description: >-
Fetches open PRs and review requests for the authenticated GitHub user,
then produces a concise digest grouped by repository.
config:
provider: anthropic
model: claude-sonnet-4-6
prompt: >-
You are a GitHub digest assistant.
1. Call `get_me` to find the authenticated user's login.
2. Call `list_pull_requests` filtering for open PRs authored by the user.
3. Call `list_pull_requests` filtering for PRs where review is requested.
4. Group results by repository. For each PR include: title, number, URL,
author, and age in days.
5. Produce a concise digest sorted by oldest first within each group.
REQUIRED: Call complete() with a summary of how many PRs were found.
The job will time out if complete() is not called.
tools:
- github/get_me # Format: serverId/toolName
- github/list_pull_requests
# ---------------------------------------------------------------------------
# Tools — configure MCP server connections
# ---------------------------------------------------------------------------
tools:
mcp:
client_config:
timeout:
progressTimeout: 2m
maxTotalTimeout: 30m
servers:
github: # Server id — referenced in agent tools lists
transport:
type: http # http | stdio
url: 'https://api.githubcopilot.com/mcp'
auth:
type: bearer
token_env: GH_TOKEN
env:
GH_TOKEN:
from: link # Reads credential from Friday Link (connected account)
provider: github
key: access_token
# ---------------------------------------------------------------------------
# Memory — define stores and cross-space mounts
# ---------------------------------------------------------------------------
memory:
own:
- name: notes
type: short_term # short_term | long_term | scratchpad
strategy: narrative
- name: memory
type: long_term
strategy: narrative
mounts:
- name: user-notes
source: user/narrative/notes
mode: ro # ro (read-only) | rw (read-write)
scope: workspace # workspace | job | agent
- name: user-memory
source: user/narrative/memory
mode: ro
scope: workspace
Field reference
version
| Field | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Always "1.0". |
workspace
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name shown in Friday Studio. |
description | string | No | One-line description of what the space does. |
signals
Each entry under signals is a named trigger. The key becomes the signal id referenced in job triggers and FSM states.
| Field | Type | Required | Description |
|---|---|---|---|
description | string | Yes | Human-readable description. |
provider | string | Yes | One of: schedule, http, fs-watch, slack, telegram, discord, whatsapp, teams. (system is reserved for internal signals.) |
config | object | Yes | Provider-specific config. See Signal providers. |
| Field | Type | Description |
|---|---|---|
schedule | string | Standard 5-field cron expression. |
timezone | string | IANA timezone string, e.g. America/Los_Angeles. |
| Field | Type | Description |
|---|---|---|
path | string | URL path that triggers the webhook, e.g. /hooks/my-trigger. The method is always POST. |
timeout | duration | Optional timeout for signal processing. |
jobs
Each entry under jobs is a named job. Jobs are FSM (finite state machine) definitions that describe which agent runs in which state and what transitions to make.
| Field | Type | Required | Description |
|---|---|---|---|
description | string | No | Human-readable description. |
triggers | array | No | List of { signal: signalId } objects. Omit for jobs invoked only from chat or run manually. |
fsm | object | Yes* | FSM definition. *A job specifies exactly one of fsm (shown here) or execution, an agent-pipeline alternative. |
fsm.initial | string | Yes | Name of the starting state. |
fsm.states | object | Yes | Map of state name to state definition. |
| Type | Fields | Description |
|---|---|---|
agent | agentId, prompt?, outputTo? | Invoke a configured agent. outputTo saves the result as a named artifact. |
llm | provider, model, prompt, tools?, outputTo? | Run an inline LLM step without defining a named agent. |
emit | event | Emit a named event to drive a state transition. |
notification | message, communicators? | Send a message to configured communicators (Slack, Telegram, …). |
agents
Each entry under agents is a named agent. The key is the agentId referenced in job FSM entry actions.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | One of: llm, atlas, user, system. |
description | string | Yes | Human-readable description. |
config | object | Varies | Agent-specific config. Required for llm; optional for system; atlas and user take top-level agent/prompt instead. |
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Inference provider. Common values: anthropic, openai, gemini, groq. |
model | string | Yes | Model identifier, e.g. claude-sonnet-4-6. |
prompt | string | Yes | System prompt for the agent. |
tools | array | No | MCP tool allowlist in serverId/toolName format. Omit to allow all tools from all enabled servers. |
| Field | Type | Required | Description |
|---|---|---|---|
agent | string | Yes | Atlas Agent ID from the registry, e.g. web, gh, slack, hubspot. |
prompt | string | Yes | Task-specific context layered on the bundled agent’s behavior. |
config | object | No | Agent-specific configuration passed to the agent. |
env | object | No | Environment variables. Values can be literals or a Link reference ({ from: link, … }). |
tools.mcp
| Field | Type | Description |
|---|---|---|
client_config.timeout.progressTimeout | duration | How long to wait between tool call progress updates before timing out. |
client_config.timeout.maxTotalTimeout | duration | Maximum total time for a single tool call. |
servers | object | Map of server id to server config. |
| Field | Type | Description |
|---|---|---|
transport.type | string | http or stdio. |
transport.url | string | For http transport: the MCP server URL. |
transport.command | string | For stdio transport: the command to run. |
transport.args | array | For stdio transport: command arguments. |
auth.type | string | bearer (the only supported value). Omit the entire auth block for servers that need no auth. |
auth.token_env | string | Name of the env var holding the bearer token. |
env | object | Env var definitions. Values can be literals or a Link reference: { from: link, key, … } with either provider (e.g. github) or a specific credential id. |
memory
| Field | Type | Description |
|---|---|---|
own | array | Memory stores owned by this space. Each entry: { name, type, strategy? }. |
mounts | array | Cross-space memory mounts. Each entry: { name, source, mode, scope, scopeTarget? }. |
| Field | Values | Description |
|---|---|---|
type | short_term, long_term, scratchpad | Retention policy. |
strategy | narrative | How entries are written and retrieved. Optional; narrative is the only value. |
| Field | Values | Description |
|---|---|---|
source | string | {spaceId}/narrative/{storeName} path to the source store. |
mode | ro, rw | Read-only or read-write access. Defaults to ro. |
scope | workspace, job, agent | How broadly the mount is visible within this space. |
scopeTarget | string | Required when scope is job or agent — the id of the job or agent to scope the mount to. Omit for scope: workspace. |
More examples
Browse the Friday Studio Examples repo for a dozen ready-made spaces with completeworkspace.yml files covering email, GitHub, Telegram, Google Sheets, price monitoring, and more.