Development environment

The development environment is where your AI agents write and test code. Think of it as a cloud-based dev machine that Superconductor spins up for each project. Your agents clone your repos, install dependencies, and run your app—all in this environment.

This is probably the trickiest part to set up, but once it's working, everything else is smooth sailing. If you get stuck, reach out to us—our team would be happy to get on a call and walk you through the setup for your specific project or to answer questions over email.

Do I need to set up a dev environment?

You can start using Superconductor right away without configuring a development environment. Here's what works and what doesn't:

Without a configured environment, agents can still read and write code, but they won't be able to run your app or see it in action. For most projects, you'll want to set this up.

Getting to the configuration settings

When you create a project and link it to GitHub, Superconductor automatically builds a minimal development environment. This default snapshot includes Node.js v24 and Python v3.14, which lets agents run basic tooling right away.

To customize your environment, go to your project dashboard and click Settings → Development Environment → Configure.

Configuring your dev environment

The development environment settings page has two main sections: Build (one-time setup) and Startup (runs each time).

Build settings

These settings determine how your environment snapshot is built. Changes here require rebuilding your environment.

Resources

Configure the compute resources for your environment:

• CPU: 2-8 cores
• Memory: 1-12 GB RAM
• Disk: 5-20 GB storage

Start with the defaults (2 CPU, 4 GB RAM, 10 GB disk) and bump them up if your builds are slow or running out of memory.

Packages

Select which language runtimes to install:

• Docker: Enable if your project needs containerization
• Node.js: Pick your version (20, 22, 24). v24 is included by default.
• Python: Pick your version (3.10, 3.11, 3.12, 3.13, 3.14). v3.14 is included by default.
• Ruby: Pick your version (3.2, 3.3, 3.4)

Only enable what you need—more packages mean longer startup times.

Secrets

Store sensitive values like API keys securely. Use them in your commands with the {{ secrets.SECRET_NAME }} syntax.

Example:

export API_KEY={{ secrets.MY_API_KEY }}

Each secret has an Export to Environment toggle. When enabled, the secret is automatically available as an environment variable ($SECRET_NAME) across all build commands, startup commands, and terminal sessions — no manual export needed. Exported secrets are shown with an "exported" badge in the development environment settings.

Secrets are encrypted and redacted from build logs.

Build commands

Commands that run once when building your environment snapshot. Use these for:

• Installing dependencies (npm install, bundle install)
• Setting up databases
• Building assets
• Any one-time setup

Important things to know:

• Each command block runs in its own shell. Exports like export API_KEY={{ secrets.API_KEY }} are only available within that block.
• cd into your repo directory first—repos are cloned to /workspace/<repo-name>
• To make environment variables available across command blocks and for running agents, enable Export to Environment on the secret. It will be exposed as $SECRET_NAME.

Example build commands for a Node.js app:

cd /workspace/my-app
npm install
npm run build

Example for a Rails app:

cd /workspace/my-rails-app
bundle install
rails db:setup

Startup settings

These settings run every time an agent starts working on your project.

Startup commands

Commands that start your development servers. The last command is automatically run in the background.

Each startup command block runs in its own shell. Secrets with Export to Environment enabled are available as $SECRET_NAME across startup command blocks.

Example for a Node.js app:

cd /workspace/my-app
npm run dev

Example for a Rails app:

cd /workspace/my-rails-app
bin/dev

HTTP services

Tell Superconductor which ports your app uses so we can create live previews.

These are the default ports for common frameworks:

We automatically create environment variables for each service:

• AGENT_WEB_HOST for a service named "web"
• AGENT_API_HOST for a service named "api"

Use these in your startup commands if your app needs to know its external URL.

Building your environment

After configuring your settings, click Save Development Environment. This triggers a build.

Tracking build progress

Watch the build log in the Terminal pane on the right side of the Dev Environment Edit page or at the top of the Dev Environment Edit page. You'll see:

1. Starting - Environment is spinning up
2. Running - Each command executes with a spinner
3. Finalizing - Snapshot is being saved

What success looks like

When the build completes successfully, you'll see a green checkmark at the top of the Dev Environment Edit page and the message:

"Development environment built successfully!"

Once built, agents can start working on tickets immediately.

What a running preview looks like

When you launch a new implementation, your startup commands automatically run. Once they complete, your live preview loads.

You can see the live App Preview above the terminal:

Troubleshooting

Build command failures

If a build command fails, you'll see the error in the terminal pane with:

• The command that failed
• Exit code
• STDOUT and STDERR output

To fix:

1. Update your build commands in Settings
2. Click Rebuild Development Environment (or Save Development Environment if you made changes)

Common issues:

• Missing dependencies: Make sure you're installing everything your app needs
• Wrong directory: Remember to cd /workspace/<repo-name> first
• Missing secrets: Check that all required secrets are configured

Startup command issues

Startup commands run each time an agent starts. If previews aren't loading:

1. Go to any Ticket Implementation in your project
2. Click Show Terminal to run the startup commands
3. Look for errors in the terminal

Common issues:

• Port already in use: Make sure you're not trying to start multiple servers on the same port
• Wrong port in HTTP services: Double-check the port matches what your app actually uses
• App crashing on startup: Check the terminal for error messages

Previews not loading

If your App Preview shows a blank page or error:

1. Check HTTP services: Is the port correct? Is "Primary" checked for the right service?
2. Check the terminal: Is your app actually running? Look for startup errors.
3. Check your app: Does it work locally? Sometimes the issue is in the app code itself.
4. Wait a moment: Some apps take a few seconds to fully start up.

Tips for success

1. Start simple: Get a basic build working before adding complexity
2. Test locally first: Make sure your setup commands work on your own machine
3. Use the terminal: It's your best friend for debugging
4. Check the logs: The terminal shows exactly what's happening
5. One thing at a time: Add commands incrementally and rebuild to verify each step

Need help?

If you're stuck, reach out to us. Our team would be happy to get on a call and walk you through the setup for your specific project or to answer questions over email. Include:

• Your project name
• What you're trying to do
• Any error messages you're seeing