Security Model
Purpose and Scope
eve’s security model is built around a boundary between the trusted application runtime and the isolated sandbox. The practical rule is that secrets stay on the trusted side, while model-directed shell and file work runs in an environment that cannot read process.env or reach back into the Node.js runtime. This page helps you review an eve agent before exposing it to production users, sensitive data, external services, or irreversible actions. It explains where data moves, where credentials live, and which controls should be explicit rather than assumed from prompt instructions alone.
Sources: docs/concepts/security-model.md
The model may influence work, but it does not become the trust boundary. It sees tool definitions, sends tool-call requests, and receives the results that tool authors return. The security decision lives in the runtime, the tool implementation, the channel route, the sandbox policy, and the deployment configuration. That distinction is important for reviewers because a well-written instruction file can reduce risk, but it cannot replace route authorization, scoped credentials, approval policies, telemetry review, or sandbox egress policy.
Sources: docs/concepts/security-model.md
Relevant Source Files
- docs/concepts/security-model.md - Defines eve’s two-context trust model, the app runtime versus sandbox comparison, the built-in shell and file tools, the data-flow diagram, credential handling examples, and deployer responsibility for data destinations and safeguards.
Trust Boundaries
The trusted side is the app runtime. This is where authored Node.js code runs, including tool implementations, model calls, connections, state management, and durable execution. It has access to process.env, which means API keys and deployment secrets should be read by runtime code rather than copied into prompts, sandbox files, model messages, or user-controlled configuration. On Vercel, the security model describes this runtime as a Vercel Function, but the important property is not the host name; it is that trusted code mediates access to privileged resources.
Sources: docs/concepts/security-model.md
The isolated side is the sandbox. The model can run shell commands there through built-in tools named bash, read_file, write_file, glob, and grep. The sandbox has its own /workspace filesystem and controlled network behavior, but it does not receive process environment variables, secrets, or a path back into the app runtime. The security document also notes that only shell commands execute in the sandbox: even the built-in tools live in the app runtime and proxy the requested operation into the sandbox.
Sources: docs/concepts/security-model.md
| Security surface | App runtime | Sandbox | Review implication |
|---|---|---|---|
process.env and secrets | Available | Not available | Keep provider keys, tokens, and deployment secrets in runtime code. |
| Authored Node.js code | Available | Not available | Implement privileged business logic as tools or connections, not as shell scripts holding secrets. |
| Network | Unrestricted by the trust table | Controlled by policy | Review runtime service calls separately from sandbox egress. |
| Filesystem | App-owned files | Isolated /workspace | Treat sandbox files as model-manipulable workspace state, not as trusted server storage. |
| Built-in tools | Defined and proxied from runtime | Shell and file effects land in sandbox | The model receives definitions and results, not direct runtime access. |
Concrete Credential Flow
The charge_card example in the security document is the simplest way to reason about secret handling. A custom tool’s execute function runs in the app runtime, reads process.env.STRIPE_KEY, calls Stripe, and returns a narrow result such as { ok: true }. The model can request the card charge and can see the returned result, but it never receives the key and the call does not pass through the sandbox. This is the pattern to prefer for any sensitive integration: privileged code owns the credential and controls the shape of the returned data.
Sources: docs/concepts/security-model.md
The built-in write_file flow is the mirror image. The tool is still runtime-owned, but the effect is intentionally proxied into the sandbox /workspace. That makes the workspace useful for generated files, analysis artifacts, and shell-oriented work without granting the shell command access to application secrets. When reviewing a new tool, ask whether it is more like charge_card or more like write_file: does it need runtime secrets and business authorization, or is it manipulating sandbox-local state under a controlled policy?
Sources: docs/concepts/security-model.md
| Source-level contract named in the security model | Where it runs | What the model sees | Security meaning |
|---|---|---|---|
Custom tool charge_card.execute | App runtime | Tool result, for example { ok: true } | Secret-backed external calls are mediated by authored code. |
process.env.STRIPE_KEY | App runtime only | Not exposed | Provider credentials remain outside the model transcript and sandbox. |
Built-in write_file | Runtime tool proxying into sandbox | Tool definition and result | File writes target sandbox /workspace, not arbitrary runtime files. |
Built-ins bash, read_file, glob, grep | Runtime definitions with sandbox effects where applicable | Tool definitions and results | Shell and file capabilities are available through controlled tools. |
Data Flow and Route Authorization
The data-flow diagram places route authorization before the eve app runtime and durable session. Inbound user or channel-provider data first reaches a channel route, then passes through route auth before model work, tool execution, or durable session processing begins. Treat that checkpoint as part of the trust boundary, not as a convenience wrapper. A channel webhook, browser session request, or service-to-service request should prove the caller and tenant context before it can create work that might persist, stream, call tools, or reach external systems.
Sources: docs/concepts/security-model.md
After the route-auth checkpoint, the runtime may send data to several configured destinations. Model inputs and outputs flow to the model provider or routing path selected in agent.ts, such as a Vercel AI Gateway model id or a provider-authored LanguageModel. Tool and connection calls may flow to external services, MCP servers, OpenAPI endpoints, and channel APIs configured by the developer. Sandbox commands may reach network destinations allowed by the sandbox network policy. Telemetry and eval data may flow to exporters and providers configured in instrumentation.ts or eval settings.
Sources: docs/concepts/security-model.md
| Data-flow checkpoint | Concrete names from the security model | What to review |
|---|---|---|
| Inbound access | Channel route and route auth | Who can start, resume, or observe agent work. |
| Runtime session | eve app runtime and durable session | What state is persisted and who can read it. |
| Model path | agent.ts, Vercel AI Gateway model id, LanguageModel | Which provider receives prompts, context, and outputs. |
| Tools and connections | Authored tools, MCP servers, OpenAPI endpoints, channels | Which external systems receive calls and credentials. |
| Sandbox egress | Sandbox network policy | Which network destinations shell commands can reach. |
| Observability | instrumentation.ts, eval settings | Which transcripts, events, or eval artifacts leave the app. |
Sessions, Persistence, and Preview Safeguards
eve stores durable session and workflow state so conversations can resume, streams can reconnect, completed steps can be replayed, and run observability can work. That durability is a reliability feature, but it is also part of the security and retention review. If a session contains customer messages, model outputs, tool results, or external-service data, the selected channels, providers, exporters, retention settings, and deletion controls need to match the sensitivity of that data. Route authorization should cover not only the first request, but also later continuation, inspection, and streaming paths in the application architecture.
Sources: docs/concepts/security-model.md
Preview and development environments need the same model even when their policies are looser. A preview deployment may use real provider keys, real channel credentials, or realistic customer data while being easier to discover than production. The safe review habit is to fail closed for externally reachable routes unless an authenticator accepts the request, and to keep local-development allowances separate from deployed access. The security model’s route-auth placement makes this sequencing clear: authentication and authorization happen before runtime work begins, not after the agent has already accepted a turn.
Sources: docs/concepts/security-model.md
Approvals and Responsible Use Boundaries
The security model explains where secrets live and where data flows, but it does not make every action safe by default. A tool can protect a credential correctly and still perform a dangerous operation if it sends money, deletes records, emails users, changes production infrastructure, or commits to an external workflow without review. For sensitive, irreversible, regulated, user-impacting, financial, healthcare, employment, housing, legal, or safety-impacting actions, require human approval or another strong safeguard before execution. Do not rely on model behavior alone to prevent misuse or accidental action.
Sources: docs/concepts/security-model.md
Approvals should be considered alongside tool restriction, connection scope, sandbox policy, schedules, subagents, and telemetry exports. Review which default tools, custom tools, MCP tools, OpenAPI connections, shell and file tools, web access, connected services, and scheduled jobs are available to the agent. Then decide which capabilities should be unavailable, tenant-scoped, user-scoped, read-only, approval-gated, or limited to local development. Scheduled and channel-triggered work deserve extra attention because they can run without a person actively watching a chat interface.
Sources: docs/concepts/security-model.md
Implementation Checklist
Start a production review by drawing the two-context boundary for your own project. List every runtime secret, configured model path, channel provider, custom tool, connection, MCP server, OpenAPI endpoint, telemetry exporter, eval provider, sandbox egress destination, and persistent state location. For each entry, record whether the model sees only a definition and result, whether sandbox commands can reach it, whether route auth has established the caller, and whether human approval is required. This turns the concept document into an auditable deployment checklist.
Sources: docs/concepts/security-model.md
Next, test the negative cases. Verify that sandbox commands cannot read process.env, that secrets are not written into /workspace, that tool results do not accidentally echo provider keys, and that unauthenticated channel requests cannot reach durable session work. Confirm that telemetry and eval exports are intentional, because observability data can contain prompts, outputs, tool results, and user context. Finally, document the expected data flow for operators so future changes to tools, connections, schedules, or model providers are reviewed against the same boundary rather than added informally.
Sources: docs/concepts/security-model.md
Related Pages and Next Steps
Read the auth and route-protection guide for endpoint-level channel authorization patterns, the tools and approvals guide for human-in-the-loop safeguards, and the sandbox guide for shell, file, and network controls. Read the execution-model page when reviewing durability, because persisted session state changes the retention and authorization conversation. Before deployment, revisit this page with your actual agent.ts, instrumentation.ts, tool files, connection configuration, and channel routes open, then confirm that every external destination and side-effecting action has an explicit policy.