Onboarding: daytonaio/daytona

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 31%)
• AGPL-3.0 licensed
• CI configured
• ⚠ Small team — 5 top contributors
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Daytona is an open-source infrastructure runtime for executing AI-generated code in secure, isolated sandboxes that spin up in under 90ms. It provides full OCI/Docker-compatible compute environments with dedicated filesystem, network stack, vCPU, and RAM, accessible via Python/TypeScript/JavaScript SDKs, a REST API, and a CLI. The core problem it solves is giving AI agents and developers a safe, reproducible, ephemeral-or-persistent compute substrate without managing containers or VMs manually. This is a monorepo: the Go backend powers the sandbox runtime and API server, TypeScript/Python/Ruby/Java SDKs live in separate SDK directories and are published independently (sdk_publish.yaml workflow), and MDX/Astro files suggest an integrated documentation site. The .devcontainer/ directory orchestrates the full local dev environment via Docker Compose with Dex (auth), PostgreSQL, pgAdmin, and an OpenTelemetry collector as sidecars.

Who it's for

AI engineers and agent workflow developers who need to safely execute untrusted or AI-generated code at scale — e.g., building coding assistants, automated code review bots, or multi-agent orchestration systems. Also DevOps/platform engineers at organizations that want to standardize sandbox infrastructure with governance controls.

Maturity & risk

The repo has a substantial multi-language codebase (Go backend, TypeScript SDK, Python/Ruby/Java client SDKs), structured CI via GitHub Actions (.github/workflows/), devcontainer setup, and automated release pipelines (prepare-release.yaml, release.yaml). The presence of e2e tests (e2e_pr_tests.yaml), linting (.golangci.yaml, .prettierrc), and a dependabot config signals active engineering discipline. Verdict: actively developed and approaching production-ready for early adopters.

The project uses a devcontainer with Dex (OIDC), PostgreSQL (pgadmin4 config visible), and OpenTelemetry collector — meaning local setup requires multiple services running simultaneously, which adds onboarding friction. Dependabot is configured (.github/dependabot.yml) but the multi-language nature (Go, TypeScript, Python, Ruby, Java) means dependency surface is large and cross-language breaking changes are a real risk. The Daytona organization appears to be the single primary maintainer, creating bus-factor risk for core Go infrastructure.

Active areas of work

Active work visible includes: automated SDK publishing (.github/workflows/sdk_publish.yaml), default image publishing (default_image_publish.yaml), a translation workflow (translate.yaml for docs), devcontainer build automation (build_devcontainer.yaml), and a batch Dependabot agent config (.claude/agents/batch-dependabot.md) suggesting AI-assisted dependency management is being integrated. Claude AI agents are being used within the repo itself for maintenance tasks.

Get running

git clone https://github.com/daytonaio/daytona.git && cd daytona

Prerequisites: Docker, VS Code with Dev Containers extension

Open in devcontainer (recommended):

code .

VS Code will prompt to 'Reopen in Container' — this starts Postgres, Dex, OTel collector

For Go development directly:

cp .env.example .env # or check .env / .envrc for required vars

Install Go dependencies:

go mod download

Install Node/TS dependencies (from repo root if nx is used):

npm install

Daily commands:

Inside devcontainer (preferred):

docker compose -f .devcontainer/docker-compose.yaml up -d

Then run the Go server:

go run ./cmd/...

Or check for a Makefile:

make run

For TypeScript SDK development:

npm install && npx nx build <sdk-package-name>

Check .envrc for direnv-managed environment variables that must be sourced

Map of the codebase

• apps/api/src/admin/admin.module.ts — Root NestJS admin module that wires together all admin-facing controllers and services, defining the core dependency injection graph for the API.
• apps/api/src/api-key/api-key.module.ts — Defines the API key authentication module — central to understanding how all requests are authorized across the platform.
• apps/api/src/api-key/api-key.service.ts — Core service implementing API key creation, validation, and revocation logic — every authenticated request flows through here.
• apps/api/src/admin/controllers/sandbox.controller.ts — Primary admin controller for sandbox (workspace) lifecycle management — the most critical resource in the Daytona platform.
• apps/api/src/admin/controllers/runner.controller.ts — Controls runner registration and management — runners are the execution hosts for AI-generated code sandboxes.
• apps/api/src/analytics/services/analytics.service.ts — Centralized analytics service capturing platform usage events — touches nearly every domain and reveals cross-cutting concerns.
• .devcontainer/devcontainer.json — Defines the canonical development environment for the entire repo including all service dependencies, ports, and toolchain versions.

How to make changes

Add a new Admin REST endpoint

1. Create a new NestJS controller file following the naming convention <resource>.controller.ts with @Controller('admin/<resource>') decorator (apps/api/src/admin/controllers/sandbox.controller.ts)
2. Create a corresponding auth spec file <resource>.controller.auth.spec.ts with tests covering unauthenticated and unauthorized scenarios (apps/api/src/admin/controllers/sandbox.controller.auth.spec.ts)
3. Register the new controller in the admin module's controllers array (apps/api/src/admin/admin.module.ts)
4. Add request/response DTOs in the dto/ directory if the endpoint accepts a request body (apps/api/src/admin/dto/create-runner.dto.ts)

Add a new API key scope or type

1. Extend the ApiKey entity to include the new scope field or enum value (apps/api/src/api-key/api-key.entity.ts)
2. Add generation and validation logic for the new scope in the API key service (apps/api/src/api-key/api-key.service.ts)
3. Expose a new endpoint or update existing endpoints in the API key controller (apps/api/src/api-key/api-key.controller.ts)
4. Add a database migration script and validate it passes the migration path validation script (apps/api/scripts/validate-migration-paths.sh)

Add a new analytics event

1. Define the new event type/payload interface and emit it via AnalyticsService in the appropriate controller or service (apps/api/src/analytics/services/analytics.service.ts)
2. Ensure the analytics module is imported in the module where the emitting service lives (apps/api/src/analytics/analytics.module.ts)

Add a new runner capability

1. Add new fields or methods to the runner controller to expose the capability via REST (apps/api/src/admin/controllers/runner.controller.ts)
2. Add a DTO for any new request body parameters (apps/api/src/admin/dto/create-runner.dto.ts)
3. Add auth boundary tests for the new endpoint (apps/api/src/admin/controllers/runner.controller.auth.spec.ts)

Why these technologies

• NestJS (TypeScript) — Provides opinionated module/DI structure needed for a large multi-domain API; decorators make auth guards, validation pipes, and OpenAPI generation ergonomic at scale.
• PostgreSQL — ACID-compliant relational store required for sandbox lifecycle state, API key management, audit logs, and runner assignments where consistency is critical.
• Docker / OCI containers — Sandboxes are container-based by design; Docker is the natural primitive for isolation, snapshotting, and image distribution of AI-generated code environments.
• OpenTelemetry (OTEL) — Vendor-neutral observability standard enables distributed tracing across API, runner hosts, and sandboxes without lock-in to a specific APM vendor.
• Dex (OIDC) — Federated identity provider allowing Daytona to support multiple upstream IdPs (GitHub, Google, etc.) without implementing OAuth flows from scratch.

Trade-offs already made

• API key authentication as primary auth mechanism

  • Why: AI agents and programmatic SDK clients need simple, stable credentials without browser-based OAuth flows.
  • Consequence: Key rotation and revocation must be managed carefully; leaked keys grant full access until explicitly revoked.

• Admin and user API surfaces separated at module level

  • Why: Strict separation prevents accidental privilege escalation and makes it easy to apply different auth guards per surface.
  • Consequence: Feature parity between admin and user APIs must be maintained in two controller trees, increasing surface area.

• Runner hosts as separate networked processes rather than in-process execution

  • Why: Elastic scaling and security isolation require sandboxes to run on separate compute, not co-located with the API process.
  • Consequence: Network latency and distributed failure modes (runner unreachable, provision timeout) must be handled explicitly.

• Monorepo with NX

  • Why: Shared toolchain, unified CI, and code sharing between API, SDKs, and tooling with incremental build caching.
  • Consequence: NX configuration complexity; new contributors must learn NX project.json conventions before contributing

Traps & gotchas

1. The devcontainer requires Docker with BuildKit enabled (buildkitd.toml is present) — plain Docker without BuildKit will fail image builds. 2) .envrc uses direnv; if not installed and hooked into your shell, environment variables won't load and the Go server will fail to start. 3) Dex OIDC in .devcontainer/dex/config.yaml likely has hardcoded callback URLs for localhost — changing ports will break auth flows silently. 4) pgAdmin credentials are stored in .devcontainer/pgadmin4/pgpass (plaintext) — do not commit real credentials here. 5) The Nx monorepo tooling (.nxignore) means you can't always run commands from arbitrary subdirectories; use nx-aware commands from root.

Architecture

Concepts to learn

• OCI Container Runtime — Daytona sandboxes are built on OCI/Docker compatibility — understanding the OCI image spec and runtime contract explains how sandboxes achieve isolation and portability.
• OIDC (OpenID Connect) — Dex is used as the OIDC provider in the devcontainer — all sandbox auth flows rely on OIDC tokens, so understanding the protocol is essential for working on auth code.
• OpenTelemetry — The OTel collector sidecar collects distributed traces and metrics from the Go backend — knowing OTLP and the collector pipeline is required to add or debug observability.
• Devcontainer Spec — The entire local dev environment is defined as a VS Code devcontainer with a custom feature (.devcontainer/tools-feature/) — contributors must understand the spec to modify the dev environment.
• Firecracker MicroVM — Sub-90ms cold-start times for sandboxes are only achievable via microVM technology like Firecracker rather than full VMs or plain containers — this is the likely underlying isolation primitive.
• Nx Monorepo Tooling — The repo uses Nx (.nxignore, likely nx.json) to manage the multi-language monorepo — build caching, affected-project detection, and task pipelines all flow through Nx.
• direnv — The .envrc file is processed by direnv to automatically inject environment variables when entering the project directory — without it, the Go server and CLI will silently misconfigure.

Related repos

• e2b-dev/e2b — Direct competitor — E2B also provides sandboxed code execution environments for AI agents with a similar SDK-first developer experience.
• coder/coder — Alternative infrastructure-for-developers platform; shares the devcontainer and remote workspace paradigm but targets human developers more than AI agents.
• firecracker-microvm/firecracker — The microVM technology that likely underlies Daytona's sub-90ms sandbox startup — understanding Firecracker explains the performance claims.
• daytonaio/daytona-provider-docker — Likely companion repo providing the Docker/OCI provider plugin for the Daytona sandbox runtime.
• opencontainers/runc — The OCI container runtime that Daytona builds on for sandbox isolation — understanding runc clarifies the security boundary model.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for Go linting and unit tests on PRs

The repo has a .golangci.yaml config already defined, meaning linting rules exist but there is no dedicated CI workflow file (e.g. .github/workflows/go_lint_test.yaml) that runs golangci-lint and go test ./... on every pull request. The existing pr_checks.yaml may be incomplete or missing Go-specific steps. Adding this ensures linting and tests are enforced on every contribution, reducing regressions for a security-critical AI code execution platform.

• [ ] Inspect .github/workflows/pr_checks.yaml to identify which Go checks (if any) are currently run
• [ ] Inspect .golangci.yaml to understand which linters are enabled and their configuration
• [ ] Create .github/workflows/go_lint_test.yaml triggered on pull_request targeting main
• [ ] Add a job that uses actions/setup-go with the correct Go version from go.mod (found in repo root)
• [ ] Add a step running golangci-lint run referencing .golangci.yaml explicitly
• [ ] Add a step running go test ./... -race -coverprofile=coverage.out to enforce test coverage
• [ ] Upload coverage artifact and optionally add a coverage summary comment to the PR

Add devcontainer smoke-test CI workflow to validate .devcontainer configuration

The repo has a rich .devcontainer setup with docker-compose.yaml, Dex OIDC, OpenTelemetry, pgAdmin4, and a custom tools-feature. There is a build_devcontainer.yaml workflow, but no workflow that actually spins up the devcontainer and runs a basic smoke test (e.g. verifying services start, ports are reachable, the tools-feature install.sh succeeds). Since Daytona positions itself as infrastructure for AI-generated code, a broken devcontainer directly harms the contributor onboarding experience and reflects poorly on the product itself.

• [ ] Inspect .devcontainer/devcontainer.json and .devcontainer/docker-compose.yaml to understand service dependencies (Dex, OTel, pgAdmin4, buildkitd)
• [ ] Inspect .devcontainer/tools-feature/install.sh to understand what the feature installs
• [ ] Inspect .github/workflows/build_devcontainer.yaml to see what is currently validated
• [ ] Create .github/workflows/devcontainer_smoke_test.yaml triggered on pull_request when .devcontainer/** files change
• [ ] Add a job using the devcontainers/ci GitHub Action to build the devcontainer image
• [ ] Add a step that executes inside the built container to verify install.sh completed (check tool binaries exist)
• [ ] Add steps to assert that docker-compose services defined in .devcontainer/docker-compose.yaml reach a healthy state

Add CONTRIBUTING guide section and runbook for the .claude/agents/batch-dependabot.md agent

The repo has a .claude/agents/batch-dependabot.md file — a Claude AI agent definition for batching Dependabot PRs — but CONTRIBUTING.md and AGENTS.md exist without any documented workflow for how contributors or maintainers should invoke, modify, or extend these Claude agents. Since Daytona is explicitly positioned as infrastructure for AI-generated code, documenting the AI agent workflows that maintain the repo itself is both on-brand and practically valuable. New contributors are left guessing how .claude/settings.json and the agents interact.

• [ ] Read .claude/agents/batch-dependabot.md to understand the agent's purpose, triggers, and expected inputs/outputs
• [ ] Read .claude/settings.json to understand global Claude agent permissions and configuration
• [ ] Read AGENTS.md and CONTRIBUTING.md to find where this documentation gap exists
• [ ] Add a dedicated section to AGENTS.md titled 'Repo Maintenance Agents' explaining the .claude/agents directory structure
• [ ] Document how

Good first issues

1. Add missing unit tests for Go handler functions — the e2e_pr_tests.yaml workflow exists but individual Go packages likely have sparse unit test coverage; pick any internal/ package and add table-driven tests. 2) The .github/ISSUE_TEMPLATE/ only has bug_report.md and feature_request.md — add a 'documentation improvement' issue template to lower the barrier for doc contributions given the large MDX surface. 3) The .claude/agents/batch-dependabot.md agent exists but likely lacks validation logic — add a CI check that verifies the agent's output PRs don't break the Go build (go build ./...) before merging.

Top contributors

• @stefanicjuraj — 20 commits
• @Tpuljak — 14 commits
• @github-actions[bot] — 12 commits
• @MDzaja — 11 commits
• @rpavlini — 7 commits

Recent commits

• 0b119c8 — feat(api,dashboard,sdk): move organization OTel config to GA (#4622) (Tpuljak)
• 812daec — fix(docs): removing stale wording around dashboard bug from oss-domain-deployment docs (#4623) (dalinkstone)
• bf7c785 — feat(docs): add cli reference installation and update (#4616) (stefanicjuraj)
• 0d52dab — feat(docs): add netbird vpn connection setup (#4618) (stefanicjuraj)
• 8b7331b — chore: sync go.sum for v0.171.0 (#4609) (github-actions[bot])
• 78e144c — chore(sdk-go): bump to v0.171.0 (#4608) (github-actions[bot])
• c4673d4 — fix (Tpuljak)
• f24b3ec — fix(api): handle buildSnapshot errors (Tpuljak)
• 4cb6495 — feat(docs): runtime sandbox network updates (#4604) (stefanicjuraj)
• f982c45 — feat(docs): agentic improvements (#4597) (stefanicjuraj)

Security observations

• Critical · Hardcoded Credentials in .env File — .env, apps/api/.env. A committed .env file exists at the root of the repository (.env) and also within apps/api/.env. Environment files containing secrets, API keys, database passwords, or other credentials should never be committed to version control. These files are visible to anyone with repository access and could expose sensitive credentials. Fix: Remove .env files from version control immediately. Add .env to .gitignore (verify it is properly excluded). Rotate any credentials that may have been exposed. Use a secrets management solution (e.g., HashiCorp Vault, AWS Secrets Manager) or environment-specific injection at deployment time. Provide a .env.example file with placeholder values instead.
• Critical · Hardcoded Credentials in DevContainer Configuration — .devcontainer/dex/config.yaml, .devcontainer/pgadmin4/pgpass, .devcontainer/pgadmin4/servers.json. The .devcontainer directory contains multiple configuration files including dex/config.yaml (OIDC provider config with likely client secrets), pgadmin4/pgpass (PostgreSQL password file), and pgadmin4/servers.json (server connection details). These files frequently contain hardcoded credentials, database passwords, and OAuth client secrets committed to the repository. Fix: Audit these files for any real credentials and rotate them immediately. Use placeholder/example values only. For pgpass files, ensure only development/test credentials are used and never production credentials. Consider using Docker secrets or environment variable substitution instead of hardcoded values.
• High · Potential SQL Injection Risk in Admin Controllers — apps/api/src/admin/controllers/. The admin controllers (audit.controller.ts, docker-registry.controller.ts, runner.controller.ts, sandbox.controller.ts) handle potentially sensitive administrative operations. Without reviewing the actual query construction, admin endpoints that accept user-supplied filtering, searching, or ordering parameters are common vectors for SQL injection if inputs are not properly parameterized. Fix: Ensure all database queries use parameterized queries or an ORM with proper escaping (e.g., TypeORM/Prisma query builders). Never concatenate user input directly into SQL strings. Perform input validation and sanitization on all query parameters. Implement integration tests specifically targeting injection attempts.
• High · Exposed pgAdmin4 Configuration with Potential Credential Leakage — .devcontainer/pgadmin4/pgpass, .devcontainer/pgadmin4/servers.json. The pgadmin4 configuration directory is committed to the repository, including a pgpass file which is a PostgreSQL password file format. This file typically contains hostname:port:database:username:password entries in plaintext. Even if intended for development, these credentials may mirror or be reused in production environments. Fix: Verify no production or shared credentials exist in these files. Ensure passwords in pgpass are unique to the development environment. Add these files to .gitignore if they contain real credentials. Use template files with placeholder values committed to the repo.
• High · DEX OIDC Provider Configuration Exposed — .devcontainer/dex/config.yaml. The Dex OIDC identity provider configuration file (.devcontainer/dex/config.yaml) is committed to the repository. Dex configurations typically contain OAuth2 client IDs, client secrets, signing keys, and connector configurations. If any of these values are real or reused across environments, they represent a significant authentication bypass risk. Fix: Audit the dex config for real secrets/keys. Rotate any OAuth client secrets or signing keys that may have been exposed. Use environment variable substitution in the config file (Dex supports this). Ensure development configs use self-generated, environment-specific secrets that are never reused in production.
• High · Docker Build Configuration May Expose Build Secrets — apps/api/Dockerfile, .devcontainer/Dockerfile, .devcontainer/buildkitd.toml. The presence of apps/api/Dockerfile and .devcontainer/Dockerfile, combined with a .dockerignore file, suggests Docker images are built from this repository. If .env files or other secrets are not properly excluded from the Docker build context, they may be baked into image layers. Additionally, buildkitd.toml configuration could expose registry credentials or build cache settings. Fix: Verify .dockerignore properly excludes all .env files, credential files, and secrets. Use Docker BuildKit secrets (--secret flag) for build-

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.