Set up your first environment

Add a Dev Container to your repository so every environment, whether started by a teammate or an agent, launches with the right runtimes, tools, and services already running.

Agents get a reproducible environment to execute commands, run tests, and iterate
New team members start an environment and immediately have everything they need
Everyone works in the same setup, no more “it works on my machine”

A Dev Container can include language runtimes, databases, tools, editor extensions, environment variables, and startup tasks.

Create your first Dev Container

Create a .devcontainer/devcontainer.json file in your repository:

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": { "moby": false }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "postCreateCommand": "npm install"
}

This gives you:

Node.js 20 with npm
Docker available inside the environment
ESLint and Prettier extensions
Dependencies installed automatically

Start an environment from your repository. Ona builds the container and you’re ready to code.

Run tasks on startup

For more control over startup behavior, use Tasks & Services:

# .ona/automations.yaml
tasks:
  install:
    name: Install dependencies
    command: npm install
    triggeredBy:
      - postDevcontainerStart

services:
  database:
    name: PostgreSQL
    commands:
      start: docker run --rm -t --name database -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:15
      ready: docker exec database pg_isready
      stop: docker stop database
    triggeredBy:
      - postEnvironmentStart

Now every environment starts with dependencies installed and a database running.

Verify it works

Once your environment starts, verify the setup. These examples assume a Node.js project. Substitute your own project’s commands:

# Check your runtime
node --version

# Run your tests (if your project has a test script)
npm test

# Start your dev server (if your project has a dev script)
npm run dev

If your project’s commands work inside the environment, your Dev Container is ready. Agents will be able to run the same commands reliably.

Next steps

Optimize startup times with prebuilds and image caching
Dev Container reference for advanced configuration: multi-container setups, private images, elevated privileges
Teach agents your codebase so they understand your conventions

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Set up your first environment

Create your first Dev Container

Run tasks on startup

Verify it works

Next steps

​Create your first Dev Container

​Run tasks on startup

​Verify it works

​Next steps

Create your first Dev Container

Run tasks on startup

Verify it works

Next steps