For AI agents: the complete documentation index is available at https://docs.flezise.com/26.09/llms.txt, the full documentation bundle is available at https://docs.flezise.com/26.09/llms-full.txt, and this page is available as Markdown at https://docs.flezise.com/26.09/sandboxes/dev-environments.md.
Docs
  • 26.09

    • Dev environments

    An agent's sandbox is a real coding environment, a place where the agent runs, builds, and tests the software, and does much more than edit files. This page explains the two paths that make it one: the project's prepared environment, applied from its stack when the sandbox starts, and the bigger environments the agent builds itself when a task needs databases, services, or a running full-stack application.

    The prepared path covers most work. The project's stack decides the language runtime, the package manager, and the developer tooling; a devenv.nix file at the repository root describes that environment, and a sandbox that finds one loads it before the agent begins. The agent's first go build or pytest finds a working toolchain instead of a bare container.

    Stacks

    Every scaffolded project has a stack: a marketplace pack that declares the language, framework, data store, directory layout, preview setup, and quality gates for one kind of application. Around twenty stack packs ship with the platform, covering categories such as full-stack web (web-fullstack-react-fastapi-postgres, the default), APIs (api-go-postgres, api-java-spring-postgres), background workers (workers-temporal, workers-python-celery), CLIs (cli-go-cobra, cli-rust-clap), and mobile (mobile-flutter, mobile-react-native).

    The stack is chosen when the high-level design is generated. A stack you picked for the project wins. Otherwise the platform scores each available stack pack against the project's requirements text and takes the best match; when nothing matches, it falls back to the bundled default. The chosen stack is bound to the project and drives the scaffold, so the repository, its service configuration, and its dev environment agree with each other from the first commit.

    How the environment is defined

    When the platform scaffolds a repository, it resolves devenv.nix in order:

    1. An explicit nix code block in the project's tech-stack artifact is used verbatim. Author one when you need exact control over the toolchain.
    2. With dev-environment template packs enabled, marketplace devenv packs matched against the tech stack are composed into the file. This source is off by default; an administrator turns it on in platform settings.
    3. Otherwise the file is derived from the detected tech keywords: each detected language family contributes its runtime plus a language server and a debug adapter, so agent tooling works out of the box. A Go project gets gopls and delve; a Python project gets pyright, ruff, and debugpy.

    A repository you import that already carries a devenv.nix keeps it; the sandbox loads whatever the file declares.

    To keep startup fast, a prebuild step after design approval builds the toolchain into a per-project store and caches the evaluated environment in the repository under .sdlc/, keyed by a hash of devenv.nix. A sandbox launch that finds a matching snapshot sources it directly; when the file has changed since the snapshot, the launch evaluates it fresh.

    Dev-environment packs

    A devenv pack is a reusable environment fragment in the marketplace. Four ship with the platform: devenv-python-ml, devenv-go-service, devenv-node-web, and devenv-rust-cli. Each pack provides:

    FileWhat it carries
    devenv.nixThe composable environment fragment: languages, packages, environment variables
    devenv.yamlMatching metadata: the language family, detection keywords, deliverable kinds, default ports
    aislop-config.ymlAn optional code-quality policy applied to the scaffold

    A pack matches a project when its declared language family is detected in the tech stack, or when one of its keywords appears there. When several packs match, their fragments are merged: the union of language settings and the union of packages, in a deterministic order.

    Packs are managed in Settings → Marketplace under the devenv and stack kinds, where you can subscribe, override, or add your own. See Marketplace.

    Note

    Stack and devenv packs define the environment a project runs in. They are separate from lifecycle blueprints, which define the SDLC pipeline a project moves through.

    Building a bigger environment

    The prepared toolchain is a starting point, not a ceiling. The agent runs arbitrary commands inside its sandbox, so when a task needs more it installs extra packages, generates code, runs migrations, and starts processes the same way you would in a terminal.

    When the software under work needs its supporting services, the agent brings them up. A repository scaffolded from a stack ships a docker-compose.yml describing its real services; the default web stack's file defines a db service running Postgres, an api service built from the backend, and a web service built from the frontend, wired together with health checks. The agent deploys that composition as a preview environment straight from the sandbox: it gets back a URL and the container list, checks per-container status and logs, and executes commands inside a running container to debug it. See Preview environments.

    Verifying what it built

    The stack declares quality gates, and the scaffolded repository carries the commands for them in .sdlc/quality-gates.yaml: a typecheck, test, build, and lint command each. The gates and the stack's pinned toolchain are placed in front of the agent during implementation, with typecheck, build, tests, and secret scanning blocking, and lint advisory. After the agent's changes, the platform's check suite runs against the workspace and any failing check is fed back into the next implementation attempt with the instruction to fix it first.

    The same check suite verifies the environment itself before a run begins; see Preflight checks.

    Next steps