Imported from yungbote/ambit-daytona (AGENTS.md). Install upstream with npx skills add yungbote/ambit-daytona. Copyright stays with the author.

Agent Development Guide

This project uses Nix flakes to provide reproducible development environments outside of the devcontainer. When working on this codebase, use the appropriate Nix dev shell to ensure all build tools, language runtimes, and dependencies are available.

Prerequisites

• Nix with flakes enabled — install guide
• Enable flakes: add experimental-features = nix-command flakes to ~/.config/nix/nix.conf

Available Dev Shells

Running Commands in Nix Shells

Interactive (human use)

nix develop .#go    # drops you into a shell with Go tools

Non-interactive (agent / CI use)

Use --command to run a single command inside the shell and exit:

nix develop .#go     --command bash -c "go build ./apps/runner/..."
nix develop .#node   --command bash -c "yarn install && yarn build"

For short commands you can also use:

nix develop .#go --command go test ./libs/common-go/...
nix develop .#go --command golangci-lint run ./apps/runner/...

Project → Shell Mapping

Use this table to determine which shell to enter for a given directory.

Go projects → nix develop .#go

All Go modules are coordinated via go.work at the repo root.

Node.js / TypeScript projects → nix develop .#node

All TS/Node projects are managed via Nx with Yarn 4 workspaces.

Common Build & Test Commands

Go

# Build all Go modules
nix develop .#go --command bash -c "go build ./..."

# Build a specific app
nix develop .#go --command bash -c "go build ./apps/runner/..."

# Run tests for a specific module
nix develop .#go --command bash -c "go test ./libs/common-go/..."

# Run tests for all Go modules
nix develop .#go --command bash -c "go test ./..."

# Lint
nix develop .#go --command bash -c "golangci-lint run ./apps/runner/..."

# Generate swagger docs
nix develop .#go --command bash -c "swag init -g apps/daemon/cmd/main.go"

# Generate netleash eBPF bindings (clang + libbpf + kernel headers are in the go shell)
nix develop .#go --command bash -c "cd libs/netleash && make generate"

# Tidy all modules
nix develop .#go --command bash -c 'for d in apps/*/go.mod libs/*/go.mod; do (cd "$(dirname "$d")" && go mod tidy); done'

Node.js / TypeScript

# Install dependencies (required first)
nix develop .#node --command bash -c "yarn install"

# Build everything
nix develop .#node --command bash -c "yarn build"

# Build a specific project
nix develop .#node --command bash -c "npx nx build api"
nix develop .#node --command bash -c "npx nx build dashboard"

# Run tests
nix develop .#node --command bash -c "npx nx test api"
nix develop .#node --command bash -c "npx nx test dashboard"

# Lint
nix develop .#node --command bash -c "yarn lint:ts"

# Format
nix develop .#node --command bash -c "npx nx format:write"

# Serve (development)
nix develop .#node --command bash -c "npx nx serve api"
nix develop .#node --command bash -c "npx nx serve dashboard"

# Generate API clients
nix develop .#node --command bash -c "yarn generate:api-client"

# Database migrations
nix develop .#node --command bash -c "yarn migration:run:pre-deploy"

Cross-language (use default shell)

# Full monorepo build
nix develop --command bash -c "yarn install && yarn build"

# Full lint
nix develop --command bash -c "yarn lint"

# Full format
nix develop --command bash -c "yarn format"

# Generate API clients
nix develop --command bash -c "yarn generate:api-client"

Monorepo Orchestration

This project uses Nx as its monorepo orchestrator. Key commands:

# See the project dependency graph
npx nx graph

# Run a target for a specific project
npx nx <target> <project>

# Run a target for all projects
npx nx run-many --target=<target> --all

# Run only affected projects (based on git changes)
npx nx affected --target=<target>

Available Nx targets: build, test, lint, serve, format, docker, docs, tidy, generate:api-client

Environment Variables

These are set automatically by the Nix shell hooks:

Supporting Services

The Nix shells provide build tools only. Runtime services (PostgreSQL, Redis, Dex, MinIO, Jaeger, etc.) are still managed via Docker Compose:

docker compose -f .devcontainer/docker-compose.yaml up -d postgres redis dex

See .devcontainer/docker-compose.yaml for the full list of available services.

Troubleshooting

yarn: command not found

Yarn 4.x is provided via a corepack wrapper in the Nix shell. Make sure you entered the node or default shell. If the issue persists:

corepack enable --install-directory ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

Go tools (swag, gow, gomarkdoc) not found

These are installed on first shell entry via go install. If they fail, install manually:

go install github.com/swaggo/swag/cmd/swag@v1.16.4
go install github.com/mitranim/gow@latest
go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@v1.1.0

Nix flake not evaluating

# Check flake syntax
nix flake check

# Update inputs (if packages are missing)
nix flake update

direnv not activating

# Allow the .envrc
direnv allow

# Verify nix-direnv is installed
nix-env -q nix-direnv