Skip to main content

​
Environment Configuration

The .aether/environment.json file defines how your workspace should be set up. It tells Aether what to run after cloning your repository — installing dependencies, running migrations, and starting background services like dev servers. This file lives in your repository and should be committed to version control so every team member and the AI agent get the same environment.

​
Quick Start

Create a .aether/environment.json file at the root of your repository: 
{
  "setup": "npm install",
  "terminals": [
    { "name": "Dev Server", "command": "npm run dev" }
  ]
}
The next time a workspace starts, Aether will install dependencies and start your dev server in the background before the agent begins working.

​
Schema Reference

All fields are optional. Only include what your project needs.
FieldTypeDescription
setupstringShell command to run after clone, before the agent starts.
terminalsarrayBackground processes to start and keep running.

​
setup

A shell command that prepares your project for development. This runs after the repository is cloned and environment variables are injected, but before the AI agent starts working. Use this for anything that needs to complete before work can begin — installing dependencies, running migrations, seeding databases. 
{
  "setup": "npm install"
}
Chain multiple commands with &&: 
{
  "setup": "npm install && npm run db:migrate"
}
The command should be idempotent (safe to run multiple times), like what a developer runs when setting up the project on a new machine.

​
terminals

An array of background processes that start automatically when the workspace boots. These keep running while the agent works — dev servers, file watchers, queue workers, etc. 
{
  "terminals": [
    { "name": "Dev Server", "command": "npm run dev" },
    { "name": "Type Check", "command": "npm run typecheck -- --watch" }
  ]
}
FieldTypeRequiredDescription
namestringYesA label for the process (shown in the UI).
commandstringYesThe shell command to run.
Terminals are restarted automatically when the workspace reboots.
The agent can also start additional services on-the-fly using the start_service tool. Those are separate from terminals and don’t persist across reboots.

​
Examples

​
Node.js / Next.js

{
  "setup": "npm install",
  "terminals": [
    { "name": "Dev Server", "command": "npm run dev" }
  ]
}

​
Python / Django

{
  "setup": "python -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python manage.py migrate",
  "terminals": [
    { "name": "Dev Server", "command": ".venv/bin/python manage.py runserver 0.0.0.0:8000" }
  ]
}

​
Ruby on Rails

{
  "setup": "bundle install && bin/rails db:prepare",
  "terminals": [
    { "name": "Rails Server", "command": "bin/rails server -b 0.0.0.0" },
    { "name": "Background Jobs", "command": "bin/jobs" }
  ]
}

​
Monorepo (Bun Workspaces)

bun install at the monorepo root resolves all workspace dependencies. Use terminals to start each app independently. 
{
  "setup": "bun install",
  "terminals": [
    { "name": "API", "command": "cd apps/api && bun run dev" },
    { "name": "Web", "command": "cd apps/web && bun run dev" }
  ]
}

​
Project with Docker Services

{
  "setup": "npm install && docker compose up -d postgres redis",
  "terminals": [
    { "name": "Dev Server", "command": "npm run dev" }
  ]
}

​
Execution Order

When a workspace starts, Aether runs the environment configuration in this order:
  1. Clone the repository
  2. Write secret files and environment variables
  3. Run setup (if configured)
  4. Start terminals in the background (if configured)
  5. Start the AI agent
If the setup command exits with a non-zero status, terminals will not start and the error is logged. Check the workspace logs for the full command output to debug failures.

​
Best Practices

  • Keep setup idempotent. Use commands like npm install or python -m venv .venv && .venv/bin/pip install -r requirements.txt that are safe to re-run. For Python, always use a virtual environment (python -m venv .venv).
  • Use setup for one-time prep, terminals for long-running processes. Installing dependencies is setup. Running a dev server is a terminal.
  • Don’t put secrets in this file. It’s committed to your repository. Use Environment Variables for API keys, database credentials, and other sensitive values.
  • Test your commands locally first. Run them manually to make sure they work before committing.
  • Chain setup commands with &&. This ensures later commands only run if earlier ones succeed.
.aether/environment.json is read at workspace boot time. If you update it while a workspace is running, the changes take effect on the next workspace restart.