Environments

An environment (env) is a named view into your database. Each Aito database starts with a single env called env.master. You can branch new envs from existing ones, write to them independently, and atomically promote them back into master — all without copying data.

Branching is a copy-on-write operation at the storage layer. Branching a 50 GB database to a new env happens in milliseconds and uses essentially no extra disk; only the changes you make in the new env take additional space.

When to use envs

  • Throwaway test sandboxes. Branch master to a sandbox, run integration tests, drop the env. Each test run gets a clean slate without re-uploading data.
  • Per-user demo copies. Give every free-trial user their own isolated env branched from a shared template. Users can mutate freely; the template stays clean.
  • Side-prepared releases. Build the next version of a dataset on the side (staging env), warm it, then atomically swap into master with one promote call. No downtime, no half-applied data.
  • Snapshot multiple scales for comparison. Branch to scale-1k, scale-10k, scale-100k envs after each ingest stage. All three remain queryable for benchmarking; old branches stay live until you drop them.

URL pattern

Every API endpoint accepts an env scope via a URL prefix:

URLResolves to
/api/v1/...env.master (default)
/env/{name}/api/v1/...the env named {name}
/api/v2/...env.master (default)
/env/{name}/api/v2/...the env named {name}

In multi-tenant deployments the env prefix nests inside the db/ prefix:

/db/{db}/api/v1/...               → master in that database
/db/{db}/env/{name}/api/v1/...    → named env in that database

Switching env is purely a URL change. Set AITO_BASE_URL=https://your-instance.aito.ai/env/sandbox/api/v1 and every existing client script targets sandbox instead of master without other modifications. Schema, data, queries, and admin all scope identically.

Managing envs

Use the _envs admin endpoints to list, branch, promote, and delete envs. See:

The same admin endpoints exist under /api/v2/_envs for the v2 API — the environment mechanism is shared across both API versions.

A read API key is required to list envs. A read-write key is required to create, delete, or promote.

Promote semantics

POST /api/v1/_envs/{name}/promote is an atomic swap, not a move:

  • After promote, env.master and the source env both reference the same underlying state. Existing queries against master see the promoted content.
  • The source env is not deleted. You can still query it under /env/{name}/api/v1/....
  • Subsequent writes to the source env do not propagate to master — they diverge. To pick the source up into master again, promote a second time.
  • To clean up the source env after a successful promote, follow with DELETE /api/v1/_envs/{name}.

This shape makes "warm and commit" workflows safe: prepare the next state on the side, verify it with full queries, then promote when ready.

Naming rules

  • Allowed characters: A-Z, a-z, 0-9, ., _, -. Must start with a letter or digit.
  • Maximum length: 128 characters.
  • Names starting with _ are reserved for system use.
  • The literal name env.master cannot be used in /env/{name}/... URLs (master is reachable via the unscoped path).

Authorization

The current model uses database-level keys: a read key reads any env in the database, a write key writes any env. There are no per-env credentials. If you need cross-tenant isolation, use separate databases (/db/{db}/...) instead of separate envs.

Memory

All active envs in a database share a single in-process cache with bounded strong-tier capacity and a SoftReference second tier. Idle envs naturally fall out of the strong cache; the JVM reclaims them under heap pressure. There is no privileged "always-resident" env — master is treated like any other entry.

For deployments serving many concurrent envs (e.g. per-user demos at scale), tune via:

  • AITO_ENV_CACHE_MAX_ENTRIES (default 100)
  • AITO_ENV_CACHE_MAX_MEMORY_PCT (default 25, % of -Xmx)
  • AITO_ENV_CACHE_TTL_MINUTES (default 30, off disables)