From 6888f1f6e089faac9effdbcdc55dc49280935238 Mon Sep 17 00:00:00 2001 From: OpenSWE Bot Date: Sat, 9 Aug 2025 00:35:17 +0000 Subject: [PATCH 1/3] Sync OpenSWE documentation files - Updated MDX files from apps/docs/ - Updated images from apps/docs/images/ - Synced at 2025-08-09 00:35:17 UTC - Source commit: 210c848997c94f29905ae50fbcb22048675a18bf --- src/labs/swe/secrets.mdx | 113 ++++++++++++++++++++++++++ src/labs/swe/setup/authentication.mdx | 41 ++++++++++ 2 files changed, 154 insertions(+) create mode 100644 src/labs/swe/secrets.mdx diff --git a/src/labs/swe/secrets.mdx b/src/labs/swe/secrets.mdx new file mode 100644 index 00000000..e63eb794 --- /dev/null +++ b/src/labs/swe/secrets.mdx @@ -0,0 +1,113 @@ +--- +title: "Secrets" +description: "Environment variables & secrets access in dev environments" +--- + +Open-SWE implements a secure, encrypted way to share user environment variables with the agent and pass them to the development server. + +## Environment Variables & API Keys + +### How API Keys Are Protected + +Your API keys are protected with industry-standard AES-256-GCM encryption both in transit and at rest. + +**Storage Process:** +1. **Frontend**: Temporarily stored in browser localStorage (plain text) +2. **Transit**: Encrypted with AES-256-GCM before sending to backend +3. **Backend**: Stored encrypted in LangGraph's database +4. **Runtime**: Decrypted when necessary using server-side encryption keys + + + **Encryption Details:** + - **Algorithm**: [AES-256-GCM](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) (authenticated encryption) + - **Key Derivation**: SHA-256 hash of system `SECRETS_ENCRYPTION_KEY` + - **IV Generation**: Random 12-byte initialization vector per encryption + - **Authentication**: 16-byte authentication tag prevents tampering + + +### System vs User Environment Variables + +Open-SWE handles two types of environment variables: + +**System Environment Variables:** +- **Purpose**: Environment variables required to run Open-SWE. If you're self-hosting, you can set LLM, infrastructure, and authentication keys +- **Examples**: `DAYTONA_API_KEY`, `SECRETS_ENCRYPTION_KEY`, `GITHUB_APP_PRIVATE_KEY` +- **Access**: Server-side only via `process.env` +- **Security**: Never exposed to users or sandboxes + +**User-Defined Environment Variables:** +- **Purpose**: Personal API keys and custom development variables +- **Examples**: `ANTHROPIC_API_KEY`, `MY_DATABASE_URL`, `STRIPE_TEST_KEY` +- **Access**: User-controlled via settings page in UI +- **Security**: AES-256-GCM encrypted + explicit user consent required to pass them to the development server + +### When API Keys Are Exposed to Sandbox Environments + +Your API keys are **never automatically exposed** to sandbox environments. Exposure requires explicit user consent. + +You may wonder, why does the sandbox environment even need API keys? We've designed Open-SWE to be your junior dev. Part of development is testing code in real-time. **Open-SWE has the ability to spin up development servers that can run your LangGraph agents, Next.js apps, Flask servers, and more, all within the sandbox its running in.** If you think this option can be useful, please review what it means to pass your keys to the sandbox. + + + Consider using separate development API keys with limited permissions instead of your production keys when enabling sandbox access. This reduces the impact of potential exposure while maintaining functionality. + + +**Default Behavior (Secure):** +- API keys are only used for LLM model initialization & setting up Daytona using your own key, if you passed it +- Keys are NOT available as environment variables in sandboxes or accessible to LLMs +- Each key has `allowedInDev: false` by default + +**When You Enable "Include in Dev Server":** +- You manually toggle the switch for each API key +- Key becomes available as an environment variable in sandbox +- You maintain control over which keys are exposed + +## Sandbox Security & Isolation + +### Container Isolation + +Each user session runs in a completely isolated Daytona container with multiple security boundaries. These containers can modify the code in your repo on a new branch and don't exchange information across sessions. + + + **Container Isolation:** + - Separate container per user session + - No shared file systems between containers + - Container-level resource limits and quotas + + **Process Isolation:** + - User environment variables vs system environment variables + - Sandboxed processes cannot access host system or code + + **Temporal Isolation:** + - Automatic deletion after 15 minutes of inactivity + - No persistent storage across sessions + - Fresh environment for each new session + + **Network Isolation:** + - Containers cannot communicate with each other + + +## Data Handling & Access Control + + + When enabling "Include in Dev Server" for API keys, you're expanding the attack surface of your credentials. AI agent may inadvertently expose environment variables in generated code or logs. Only use this feature when necessary for development server monitoring. + + +### Development Environment Exposure Risks + +You should only use this feature if you find it useful to monitor development servers. We recommend not using your main keys and having access control for keys that you pass to sandbox environments. + +While the Open-SWE UI and agent exchange these using encryption, **LLM may leave environment variables exposed in the code.** + +## Security Best Practices + +Our team loves using Open-SWE internally and we recommend the following best practices: + +- Use the minimum required permissions for each API key +- Regularly rotate your API keys +- Only enable "Include in Dev Server" when necessary for specific tools +- Monitor the "Last Used" timestamps in settings +- Consider using separate development keys instead of production keys for sandbox environments +- Never enable sandbox access for production database credentials or high-privilege API keys +- Review generated code for accidentally exposed environment variables before deploying + +--- \ No newline at end of file diff --git a/src/labs/swe/setup/authentication.mdx b/src/labs/swe/setup/authentication.mdx index c4353966..891ba47b 100644 --- a/src/labs/swe/setup/authentication.mdx +++ b/src/labs/swe/setup/authentication.mdx @@ -35,6 +35,47 @@ The Next.js application includes a proxy route (`apps/web/src/app/api/[..._path] with the LangGraph server. +## Simple API Key (Bearer) Authentication + +For local development and scripted access, the LangGraph server also supports a simple bearer token scheme. When a request includes an `Authorization: Bearer ` header, this path is used and the rest of the auth flow is skipped. + +### Setup (development) + +- **Generate a token** (32+ bytes, URL-safe): + - OpenSSL: `openssl rand -hex 32` +- **Add to your `.env` for the LangGraph server**: + +```bash +API_BEARER_TOKEN= +``` + +- For multiple/rotation: use comma-separated tokens + +```bash +API_BEARER_TOKENS=,, +``` + +Restart the LangGraph server after updating environment variables. + +### Usage + +```typescript +import { Client } from "@langchain/langgraph-sdk"; + +const client = new Client({ + apiUrl: process.env.LANGGRAPH_API_URL, + defaultHeaders: { + authorization: `Bearer ${process.env.API_BEARER_TOKEN}`, + }, +}); +``` + +### Notes + +- **Precedence**: If the `Authorization` header is present, bearer auth is used; otherwise the existing GitHub-based flow applies. +- **Rotation**: Add a new token to `API_BEARER_TOKENS`, deploy/restart, migrate clients, then remove old tokens and redeploy. +- **Scope**: All bearer tokens currently map to the same internal identity and permissions. If you need per-token identities/quotas, reach out to adjust the configuration. + ### Header Injection System The proxy route automatically injects the following encrypted headers into each request: From 196ceb6afcb9a8543066222118d7e2c238430ef5 Mon Sep 17 00:00:00 2001 From: bracesproul Date: Fri, 8 Aug 2025 20:51:29 -0700 Subject: [PATCH 2/3] cr --- src/docs.json | 6 ++ src/labs/swe/index.mdx | 4 +- src/labs/swe/secrets.mdx | 118 +++++++++++++-------------------------- 3 files changed, 48 insertions(+), 80 deletions(-) diff --git a/src/docs.json b/src/docs.json index a0832819..2cb9d0ec 100644 --- a/src/docs.json +++ b/src/docs.json @@ -356,6 +356,12 @@ "labs/swe/setup/ci" ] }, + { + "group": "Secrets", + "pages": [ + "labs/swe/secrets" + ] + }, { "group": "FAQ", "pages": [ diff --git a/src/labs/swe/index.mdx b/src/labs/swe/index.mdx index 84592a20..1244e0de 100644 --- a/src/labs/swe/index.mdx +++ b/src/labs/swe/index.mdx @@ -21,8 +21,8 @@ The agent can be used through a web interface or triggered automatically via Git How to set up Open SWE for development - - Examples of tasks you can try out + + Frequently asked questions Open SWE features, and how to use them diff --git a/src/labs/swe/secrets.mdx b/src/labs/swe/secrets.mdx index e63eb794..56bfe03f 100644 --- a/src/labs/swe/secrets.mdx +++ b/src/labs/swe/secrets.mdx @@ -3,111 +3,73 @@ title: "Secrets" description: "Environment variables & secrets access in dev environments" --- -Open-SWE implements a secure, encrypted way to share user environment variables with the agent and pass them to the development server. +Open-SWE securely manages your API keys and environment variables with AES-256-GCM encryption. -## Environment Variables & API Keys +## How Your API Keys Are Protected -### How API Keys Are Protected +Your API keys are encrypted both in transit and at rest: -Your API keys are protected with industry-standard AES-256-GCM encryption both in transit and at rest. - -**Storage Process:** -1. **Frontend**: Temporarily stored in browser localStorage (plain text) -2. **Transit**: Encrypted with AES-256-GCM before sending to backend -3. **Backend**: Stored encrypted in LangGraph's database -4. **Runtime**: Decrypted when necessary using server-side encryption keys +1. **Frontend**: Temporarily stored in browser localStorage +2. **Transit**: Encrypted before sending to backend +3. **Backend**: Stored encrypted in database +4. **Runtime**: Decrypted only when needed - **Encryption Details:** - **Algorithm**: [AES-256-GCM](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) (authenticated encryption) - **Key Derivation**: SHA-256 hash of system `SECRETS_ENCRYPTION_KEY` - **IV Generation**: Random 12-byte initialization vector per encryption - **Authentication**: 16-byte authentication tag prevents tampering -### System vs User Environment Variables +## Types of Environment Variables -Open-SWE handles two types of environment variables: +**System Variables** (for self-hosting): +- Examples: `DAYTONA_API_KEY`, `SECRETS_ENCRYPTION_KEY`, `GITHUB_APP_PRIVATE_KEY` +- Access: Server-side only, never exposed to users or sandboxes -**System Environment Variables:** -- **Purpose**: Environment variables required to run Open-SWE. If you're self-hosting, you can set LLM, infrastructure, and authentication keys -- **Examples**: `DAYTONA_API_KEY`, `SECRETS_ENCRYPTION_KEY`, `GITHUB_APP_PRIVATE_KEY` -- **Access**: Server-side only via `process.env` -- **Security**: Never exposed to users or sandboxes +**User Variables** (your personal keys): +- Examples: `ANTHROPIC_API_KEY`, `MY_DATABASE_URL`, `STRIPE_TEST_KEY` +- Access: Controlled via settings page, encrypted storage -**User-Defined Environment Variables:** -- **Purpose**: Personal API keys and custom development variables -- **Examples**: `ANTHROPIC_API_KEY`, `MY_DATABASE_URL`, `STRIPE_TEST_KEY` -- **Access**: User-controlled via settings page in UI -- **Security**: AES-256-GCM encrypted + explicit user consent required to pass them to the development server +## Sandbox Access Control -### When API Keys Are Exposed to Sandbox Environments +**By default, your API keys are never exposed to sandbox environments.** They're only used for LLM initialization and system setup. -Your API keys are **never automatically exposed** to sandbox environments. Exposure requires explicit user consent. +To enable keys in development servers (for testing LangGraph agents, Next.js apps, etc.): -You may wonder, why does the sandbox environment even need API keys? We've designed Open-SWE to be your junior dev. Part of development is testing code in real-time. **Open-SWE has the ability to spin up development servers that can run your LangGraph agents, Next.js apps, Flask servers, and more, all within the sandbox its running in.** If you think this option can be useful, please review what it means to pass your keys to the sandbox. +1. Manually toggle "Include in Dev Server" for each key +2. Key becomes available as environment variable in sandbox +3. You control which keys are exposed - Consider using separate development API keys with limited permissions instead of your production keys when enabling sandbox access. This reduces the impact of potential exposure while maintaining functionality. + Use separate development API keys with limited permissions instead of production keys when enabling sandbox access. -**Default Behavior (Secure):** -- API keys are only used for LLM model initialization & setting up Daytona using your own key, if you passed it -- Keys are NOT available as environment variables in sandboxes or accessible to LLMs -- Each key has `allowedInDev: false` by default - -**When You Enable "Include in Dev Server":** -- You manually toggle the switch for each API key -- Key becomes available as an environment variable in sandbox -- You maintain control over which keys are exposed - -## Sandbox Security & Isolation - -### Container Isolation - -Each user session runs in a completely isolated Daytona container with multiple security boundaries. These containers can modify the code in your repo on a new branch and don't exchange information across sessions. - - - **Container Isolation:** - - Separate container per user session - - No shared file systems between containers - - Container-level resource limits and quotas - - **Process Isolation:** - - User environment variables vs system environment variables - - Sandboxed processes cannot access host system or code +## Security & Isolation - **Temporal Isolation:** - - Automatic deletion after 15 minutes of inactivity - - No persistent storage across sessions - - Fresh environment for each new session +Each session runs in an isolated Daytona container that: +- Cannot access other user sessions +- Automatically deletes after 15 minutes of inactivity +- Has no persistent storage across sessions - **Network Isolation:** - - Containers cannot communicate with each other + + - **Container**: Separate container per user session + - **File System**: No shared file systems between containers + - **Process**: Sandboxed processes cannot access host system + - **Network**: Containers cannot communicate with each other + - **Temporal**: Fresh environment for each session -## Data Handling & Access Control - - When enabling "Include in Dev Server" for API keys, you're expanding the attack surface of your credentials. AI agent may inadvertently expose environment variables in generated code or logs. Only use this feature when necessary for development server monitoring. + When enabling "Include in Dev Server", the AI agent may inadvertently expose environment variables in generated code or logs. Only enable when necessary. -### Development Environment Exposure Risks - -You should only use this feature if you find it useful to monitor development servers. We recommend not using your main keys and having access control for keys that you pass to sandbox environments. - -While the Open-SWE UI and agent exchange these using encryption, **LLM may leave environment variables exposed in the code.** +## Best Practices -## Security Best Practices - -Our team loves using Open-SWE internally and we recommend the following best practices: - -- Use the minimum required permissions for each API key +- Use minimum required permissions for each API key - Regularly rotate your API keys -- Only enable "Include in Dev Server" when necessary for specific tools -- Monitor the "Last Used" timestamps in settings -- Consider using separate development keys instead of production keys for sandbox environments -- Never enable sandbox access for production database credentials or high-privilege API keys -- Review generated code for accidentally exposed environment variables before deploying - ---- \ No newline at end of file +- Use separate development keys instead of production keys for sandbox access +- Only enable "Include in Dev Server" when necessary +- Never enable sandbox access for production database credentials +- Review generated code for exposed environment variables before deploying +- Monitor "Last Used" timestamps in settings From 90430a6c73eb3d73e1803954bd239601ea2ff01b Mon Sep 17 00:00:00 2001 From: Lauren Hirata Singh Date: Fri, 15 Aug 2025 10:01:04 -0700 Subject: [PATCH 3/3] Update src/labs/swe/index.mdx --- src/labs/swe/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/labs/swe/index.mdx b/src/labs/swe/index.mdx index b7026ac7..96b33edd 100644 --- a/src/labs/swe/index.mdx +++ b/src/labs/swe/index.mdx @@ -23,6 +23,7 @@ The agent can be used through a web interface or triggered automatically via Git Frequently asked questions + Examples of tasks you can try out