Environments

Environments allow you to connect your GitHub repositories and manage environment variables securely for your projects. Each environment links to a specific repository and can store encrypted variables that are automatically injected into your sandboxes during development.

Why Use Environments?

Environments help you:

• Connect to GitHub repositories - Link your code repositories for seamless integration
• Manage secrets securely - Store API keys, tokens, and other sensitive data with AES-256-GCM encryption
• Streamline development - Automatically inject variables into sandboxes without manual configuration
• Organize projects - Create separate environments for different repositories or deployment stages

All environment variables are encrypted at rest and only decrypted when needed, ensuring your sensitive data stays protected.

Creating Your First Environment

Follow these steps to create a new environment:

1. Navigate to environments - Go to your workspace settings and click the "Create Environment" button

2. Connect to GitHub - If this is your first time, you'll need to authenticate with GitHub:

   • Click the GitHub authentication button
   • Authorize the application to access your repositories
   • Grant permissions to the organizations you want to access

3. Select your GitHub organization - If you have access to multiple GitHub organizations or installations, choose the one that contains your repository

4. Choose a repository - Search for and select the repository you want to link:

   • Use the search bar to filter repositories by name
   • You'll see both public and private repositories you have access to
   • The environment name will automatically populate based on your repository name

5. Add environment variables (optional) - You can add variables now or later:

   • Expand the "Environment Variables" section
   • Add key-value pairs manually, or
   • Paste an entire .env file (see tips below)

6. Create the environment - Click "Create environment" and you're done!

Your environment is now ready to use with projects and chat sessions.

Managing Environment Variables

Environment variables are key-value pairs that store configuration and secrets for your application. All values are automatically encrypted before being stored.

Adding Variables Manually

To add variables one at a time:

1. Expand the "Environment Variables" section in the environment form
2. Enter a variable name (key) in the first field, such as DATABASE_URL or API_KEY
3. Enter the variable value in the second field
4. Click "Add More" to add additional variables
5. Remove unwanted variables by clicking the delete (×) button

Pasting .env Files

Save time by pasting your entire .env file:

1. Click into the first empty variable field
2. Paste your .env file contents directly into the field
3. The system will automatically parse your file and create individual variables

What gets parsed:

• Lines in KEY=VALUE format
• Values with or without quotes (KEY="value" or KEY=value)
• Multiple variables separated by newlines

What gets ignored:

• Empty lines
• Comments (lines starting with #)
• Duplicate keys already in your environment

Example .env file:

# Database configuration
DATABASE_URL=postgresql://localhost:5432/mydb
DATABASE_POOL_SIZE=10

# API Keys
STRIPE_SECRET_KEY=sk_test_abc123
SHOPIFY_API_KEY=shpat_xyz789

# Feature Flags
ENABLE_BETA_FEATURES=true

This is the fastest way to import multiple variables at once!

Security & Encryption

Your environment variables are protected with industry-standard security:

• AES-256-GCM encryption - All variable values are encrypted before storage
• Encrypted at rest - Values are never stored in plain text
• Decrypted on-demand - Values are only decrypted when needed for sandboxes
• Secure transmission - All API requests use HTTPS encryption

When viewing existing variables, you'll see ••• placeholders instead of actual values. This is normal - it means your values are safely encrypted. To update a value, simply type a new one.

⚠️ Important Security Notes:

• Never commit .env files to your Git repository
• Rotate secrets regularly, especially if they may have been exposed
• Use different values for development and production environments
• Only grant workspace access to trusted team members

Updating Environments

You can modify your environments at any time:

Editing Environment Details

1. Find the environment you want to edit
2. Click the edit button (pencil icon)
3. Update the environment name if needed
4. Note: You cannot change the linked repository after creation

Modifying Environment Variables

When editing an environment, you can:

Update existing variables:

• Click into the value field (showing •••)
• Type your new value
• An orange indicator will show the variable has been modified
• You can also change the key name if needed

Add new variables:

• Scroll to the bottom of the variables list
• Click "Add More" to create new variable fields
• Enter the key and value
• Or paste additional .env content into any empty field

Delete variables:

• Click the delete (×) button next to any variable
• The variable will be removed when you save changes

Save your changes:

• Click "Save Changes" to apply all modifications
• Only modified variables are updated (efficient saving)
• Deleted variables are permanently removed

Deleting an Environment

To delete an environment completely:

1. Click the delete button for the environment
2. A confirmation dialog will appear
3. Type the exact environment name to confirm deletion
4. Click "Delete environment"

⚠️ Warning: Deleting an environment also deletes all associated environment variables. This action cannot be undone.

Using Environments

Once created, your environments can be used throughout the platform:

Linking to Projects

When creating or editing a project, you can select an environment to associate with it. This makes it easy to maintain consistent configuration across your project's development workflow.

Using in Chat Sessions

When working in a chat session with sandbox capabilities:

1. Click the environment selector in the chat interface
2. Choose the environment you want to use
3. All environment variables from that environment will be automatically injected into the sandbox
4. Your code can access these variables through the standard process environment (e.g., process.env.DATABASE_URL in Node.js)

This means you don't need to manually configure environment variables every time you start a new sandbox session.

Variable Injection

When an environment is selected:

• Variables are automatically injected into the sandbox instance
• They're available immediately when your development server starts
• They work just like local environment variables in your development environment
• The actual encrypted values are decrypted only within the secure sandbox

Best Practices

Follow these guidelines to get the most out of environments:

Naming Conventions

• Environment names: Use descriptive names that match your repository or purpose

  • Good: my-app-production, ecommerce-staging, api-backend
  • Avoid: env1, test, temp

• Variable names: Use clear, uppercase names with underscores

  • Good: DATABASE_URL, STRIPE_SECRET_KEY, MAX_CONNECTIONS
  • Avoid: key, secret, x

Organization Strategies

Single repository, multiple stages: Create separate environments for different deployment stages:

• my-app-development with dev/test credentials
• my-app-staging with staging credentials
• my-app-production with production credentials (be extra careful!)

Multiple repositories: Create one environment per repository:

• frontend-app for your React/Next.js application
• api-backend for your API server
• workers-service for your Cloudflare Workers

Shared variables: For variables used across multiple projects:

• Create a base environment with common variables
• Document which environment contains shared configuration
• Keep sensitive production credentials in separate environments

Security Recommendations

1. Principle of least privilege: Only add variables that are actually needed for the environment
2. Regular rotation: Update secrets periodically, especially API keys and tokens
3. No production secrets in development: Use different credentials for dev/staging/production
4. Audit access: Regularly review who has access to your workspace and environments
5. Use strong values: Generate random, complex values for tokens and secrets
6. Document non-secret variables: For non-sensitive configuration, consider documenting defaults in your repository's README

When to Create Multiple Environments

Create separate environments when you:

• Work with different repositories
• Need different variable values for dev/staging/production
• Want to isolate credentials for different services
• Have different teams working on different parts of a system
• Need to test with different configurations

Troubleshooting

GitHub Connection Issues

Problem: Can't see my repositories after authenticating with GitHub

Solutions:

1. Verify you've installed the GitHub app on your organization:
   • Click the "Configure on GitHub" link in the repository selector
   • Check which repositories are accessible
   • Grant access to the specific repositories you need
2. Refresh the repository list by closing and reopening the dialog
3. Try logging out and back in to refresh your GitHub authentication
4. Ensure you have at least read access to the repository

Problem: Repository list is empty or incomplete

Solutions:

1. Select the correct GitHub organization/installation from the dropdown
2. Check that the GitHub App installation hasn't been revoked
3. Verify your GitHub account has access to the repositories
4. For private repositories, ensure the app has permission to access private repos

Variable Access Issues

Problem: Environment variables aren't showing up in my sandbox

Solutions:

1. Verify you've selected the correct environment in the chat session
2. Check that the environment is properly linked to your project
3. Restart the sandbox to reload environment variables
4. Ensure the variables are actually saved in the environment (check the edit dialog)

Problem: Can't see my variable values when editing

Solution: This is expected behavior! Variable values are encrypted and display as ••• for security. To update a value, simply type a new one in the field. The system knows you've made a change and will update it when you save.

Problem: Variables appear with an orange dot indicator

Solution: This means you've modified the variable since opening the dialog. It's a helpful indicator to show what's changed. Click "Save Changes" to apply your updates, or close the dialog to discard changes.

Environment Creation Issues

Problem: Can't create an environment

Solutions:

1. Ensure you're logged in and have workspace access
2. Verify your GitHub authentication is still valid
3. Check that you've selected a repository
4. Make sure you've filled in all required fields (environment name)
5. If using .env paste, verify the format is correct (KEY=VALUE)

Problem: .env file paste isn't parsing correctly

Solutions:

1. Ensure your .env file uses the format: KEY=VALUE
2. Check for syntax errors like missing = signs
3. Remove any unusual characters or formatting
4. Try adding variables manually if paste continues to fail
5. Verify there are no duplicate keys already in your environment

When to Contact Support

Reach out for help if you encounter:

• Persistent GitHub authentication failures
• Environments not saving or loading correctly
• Variable encryption/decryption errors
• Missing environments that were previously created
• Workspace permission issues
• Any error messages that persist after trying the solutions above

We're here to help ensure your environments work smoothly and securely!