Environments

An environment (or env) in Papayya is a named separation boundary: a separate project, a separate API key, and a separate bucket of agents, runs, items, schedules, triggers, secrets, and usage. Envs let you run dev, staging, and prod side-by-side from a single CLI install without ever crossing wires.

Model

Each env is a Papayya project under the hood — so slugs, budgets, and rate cards are scoped per env. There is no global "prod agent" that spans environments; instead, the same ops-bot name can live in each env and point to a different deployed agent in each one.

Env names are user-defined free-form strings. dev, staging, prod, acme-customer-a — any string you type.

Config lives in ~/.papayya/config.json:

{
  "version": 2,
  "current_env": "dev",
  "envs": {
    "dev":     { "api_key": "cpk_dev...",     "project_id": "p-dev",     "base_url": "..." },
    "staging": { "api_key": "cpk_staging...", "project_id": "p-staging", "base_url": "..." }
  }
}

Managing envs

papayya envs list               # show all envs; current is marked
papayya envs use <name>         # switch the default env for your shell
papayya envs create <name>      # provisions a new project + API key, persists locally
papayya envs link <name>        # link an existing dashboard-created project

See the envs CLI section for the full flag list.

How `--env` interacts with commands

Every server-hitting command honors a global --env <name> flag (and the PAPAYYA_ENV env var). When set, the command resolves its API key, project ID, and base URL from that env instead of current_env:

PAPAYYA_ENV=staging python agent.py
papayya --env staging status <run-id>
papayya --env staging secrets set OPENAI_API_KEY sk-...
papayya --env staging rate-card show

Omitting --env falls back to current_env. An explicit --api-key / --base-url / --project-id flag always wins over the env's stored values.

dev → prod promotion

Promotion is a redeploy, not a copy. You develop against dev, then deploy the same code into prod under the same agent name:

papayya deploy --env dev     # iterate here — runs land in the dev project
papayya deploy --env prod    # same code, prod project, prod schedules + triggers

Because each env is its own project, a dev run and a prod run of the same agent never share a ledger, a budget, or a rate card. Point your dashboard (or --env) at the env you want to inspect.

Schedules and triggers are per-agent, in code

Envs don't declare schedules or triggers — the agent does, via @schedule / @trigger decorators in its source. Deploying the same agent into a different env reconciles that agent's decorated schedules and triggers against that env's project:

papayya deploy --env prod    # bundles your code, reconciles this agent's @schedule/@trigger into prod

Because each env is its own project, the same decorated schedule produces independent runs per env. See Schedules & Triggers for the full model.

Non-goals (for now)

Org / team scopes. Projects are owned by accounts today; multi-user org support is post-launch.
Single-project rollup across envs. Today each env is a distinct project; if you later need cross-env billing rollup, that will be a server-side migration.
Per-env runtime config overrides. Model, budget, and tool set live on the agent's @agent decorator — not per env. Agent config travels with the code you deploy into each env.

Overview Runs