> ## Documentation Index
> Fetch the complete documentation index at: https://felan.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Security architecture
> How Felan separates orchestration from OS-level execution, scopes credentials, and isolates agent workspaces.
Felan separates the agent that coordinates a request from the environment that runs operating-system tools. This boundary limits which credentials and data are available to shell commands, repository tooling, browsers, and delegated agents.
## Runtime and workspace separation
Each team has an **agent runtime** that manages conversations, sessions, model access, integrations, and delegation. Work that needs machine access runs in a separate **agent workspace**.
```text theme={null}
Team agent runtime
├─ conversation and session orchestration
├─ model and platform credentials
└─ sandbox-routed tools
│
▼
Isolated agent workspace
├─ repository working copies
├─ shell and filesystem tools
├─ browser automation
└─ task-specific environment values
```
In production, the agent workspace is a separate Daytona sandbox created from a versioned workspace snapshot. Local development and evaluation runs use a Docker container created from the corresponding workspace image.
The workspace is the execution boundary for tools such as `bash`, `read`, `write`, `edit`, `grep`, `find`, and `ls`. Tool calls are routed into the workspace instead of running directly in the agent runtime.
## Session isolation and reuse
A root session receives its own agent workspace when machine access is first required. Delegated subagents within that root session can share the same workspace so they can collaborate on the same checked-out files. A different root session receives a different workspace.
This means Felan does not create a new sandbox for every command or every delegated subagent. The security boundary is between root-session workspaces and between the workspace and the team agent runtime.
Workspace identifiers are persisted with sessions so an interrupted session can resume the same provider sandbox when it is still available. If it cannot be resumed, Felan creates a fresh workspace from authorized repository clones and reports that uncommitted workspace state was not recovered.
## Credential boundaries
The agent runtime keeps platform-level credentials out of the agent workspace environment. The workspace environment filter explicitly removes:
* Model credentials
* Supabase and service-role credentials
* Team API keys
* Slack, Microsoft Teams, and email provider credentials
* Observability and encryption credentials
* Daytona platform credentials
Repository and integration access is prepared by the platform for the current team and request. Give Felan only the repositories, integrations, environments, and credentials required for the work.
Customer Supabase connections use a dedicated OAuth app with `projects:read` and `database:read`. The isolated workspace receives the refreshed provider token and selected project reference when the Supabase skill is active. Its bundled CLI calls only Supabase's SQL endpoint that executes as `supabase_read_only_user`, while local validation bounds statements, rows, duration, and output size.
The Supabase OAuth token is scoped to the authorizing identity rather than one project reference. The reference constrains normal CLI requests, while the token may authorize read-scoped Management API calls for other projects available to that identity. Connect a least-privilege Supabase identity whose project access matches the data Felan may inspect.
An isolated workspace can still access the files, environment values, connected services, and network destinations intentionally provided to it. Use scoped test accounts, least-privilege provider permissions, and non-production data whenever possible.
## Files, transcripts, and generated work
Repository working copies and command outputs are produced inside the agent workspace. Session transcripts and conversation state remain outside that workspace in Felan's session storage.
This separation prevents an OS-level tool from receiving the agent runtime's full conversation state or platform credential set by default. Relevant instructions, repository content, and task-specific values are still available when the request requires them.
## Network access
Agent workspaces allow outbound network access by default because software work may require repository clones, package installation, browser access to an application, and connected service APIs.
For services that are not publicly reachable, [Private Connectivity](/docs/platform/settings#private-connectivity) provides a team-managed path to approved private endpoints. Network isolation is not a substitute for provider permissions: connected services should still use narrowly scoped credentials.
## Workspace lifecycle
Felan creates production workspaces from a pinned Daytona snapshot rather than installing the execution environment for every request. Workspaces can stop when idle, resume for continued session work, and be replaced when their snapshot is stale or the provider sandbox is unavailable.
Local Docker workspaces use separate containers and support resource and process controls configured by the development environment. They are intended for trusted local development and evaluation, while production uses the Daytona sandbox backend.
## What the sandbox boundary provides
The workspace design provides:
* A separate process and filesystem boundary for OS-level tools
* Separation between agent runtime credentials and workspace inputs
* A workspace scoped to one root session's machine state
* Source-visible routing of shell, filesystem, and browser work through the workspace backend
* A recoverable lifecycle that can stop, resume, or recreate the workspace
It does not make arbitrary commands risk-free or remove the need for least-privilege access. Review connected repositories, environment values, automation instructions, and provider permissions as part of your team's security process.
See how root sessions and delegated work are organized.
Manage team access, API keys, models, environments, and Private Connectivity.