Skip to main content
A Dev Container defines everything your project needs to run - language runtimes, databases, tools, and configuration. When you define one, every environment starts identically, whether it’s you, a teammate, or an Ona agent.

​
Why Dev Containers matter

Without a Dev Container, environments are inconsistent. Agents can’t reliably run your test suite if they don’t know how to set up the database. New team members spend hours configuring their machines. Bugs appear that “work on my machine.” A Dev Container solves this by codifying your environment:
  • Agents get a run loop: With a reproducible environment, agents can execute commands, run tests, observe results, and iterate. They can try something, see it fail, and try again - all in an environment they understand. This is what makes agents successful at completing complex, multi-step tasks autonomously.
  • Instant onboarding: New team members start an environment and immediately have everything they need - the right Node version, the database running, dependencies installed.
  • Parity across the team: Everyone works in the same environment. No more “it works on my machine.”

​
What you can define

A Dev Container can include:
  • Language runtimes: Node.js, Python, Go, Rust, Java, etc.
  • Databases: PostgreSQL, MySQL, Redis, MongoDB
  • Tools: Docker, kubectl, AWS CLI, Terraform
  • Editor extensions: Linters, formatters, language servers
  • Environment variables: API keys, configuration
  • Startup tasks: Install dependencies, seed databases, start services

​
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": {}
  },
  "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
    command: docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:15
    triggeredBy:
      - postDevcontainerStart
Now every environment starts with dependencies installed and a database running.

​
Verify it works

Once your environment starts, verify the setup: 
# Check your runtime
node --version

# Run your tests
npm test

# Start your dev server
npm run dev
If these work, your Dev Container is ready. Agents will be able to run the same commands reliably.

​
Next steps