Scenarios

Scenarios define the starting state for one or more digital twins. They can contain Slack channels with message history, Stripe customers with subscriptions, GitHub repositories with open pull requests, and other provider-specific data. Use a Scenario when you want a short-lived Twin Run to start from known data or a persistent twin environment to return to the same baseline after a reseed.

Preset scenarios

Arga ships with 10 built-in scenario templates covering common testing patterns. These are available to all users and can be cloned to customize.

Functionality

Scenario	Twins	What’s inside
E-commerce Checkout	Stripe, Slack	3 customers on free/pro/enterprise plans, #orders channel with purchase confirmations, #support with billing questions
SaaS Billing & Upgrades	Stripe, Slack, Notion	Trial user expiring in 2 days, free/pro/enterprise customers, monthly+annual pricing, #billing alerts, pricing docs
DevOps CI/CD Pipeline	GitHub, Slack, Discord	2 repos (passing and failing CI), merged and open PRs, #deploys and #incidents channels, #dev-alerts Discord
Customer Support Portal	Slack, Stripe, Notion	#support-tier1 with 8 open tickets, #support-escalated with 2 critical issues, disputed charges, knowledge base articles
Document Collaboration	Google Drive, Slack, Notion	Q2 Planning shared folder with 4 docs, #team-docs with file share notifications, project wiki pages

Security

Scenario	Twins	What’s inside
Payment Fraud & Edge Cases	Stripe, Slack	Declined cards (insufficient funds, expired, stolen), $500 chargeback, partial refunds, #fraud-alerts channel
Access Control & Auth Boundaries	GitHub, Slack, Notion	Protected branches, outside contributor PRs, confidential issues, admin/member/guest Slack roles, mixed-permission Notion pages

Edge cases

Scenario	Twins	What’s inside
High Volume Messaging	Slack, Discord	50+ messages in #general, 20 threaded discussions, 5 DM conversations, 30+ Discord messages per channel with embeds
Internationalization & Unicode	Slack, Stripe, Notion	Messages in Japanese/Arabic/Portuguese, emoji-heavy content, international addresses (JP, DE, BR), multi-currency (USD/EUR/JPY), RTL text
Calendar Scheduling Conflicts	Google Calendar, Slack	Overlapping meetings, back-to-back events, all-day events across timezones, cancelled-but-visible meetings, #scheduling channel

Using presets

From the web app: Open Scenarios in the sidebar. Preset templates appear at the top. Select Use in Run to open a Twin Run with that Scenario, or Clone to save an editable copy. From the API:

# List all presets
curl https://api.argalabs.com/scenarios/presets

# Filter presets by twin
curl "https://api.argalabs.com/scenarios/presets?twin=stripe"

From the CLI:

# Provision twins from a preset
arga previews twins provision \
  --twins stripe,slack \
  --scenario-id <preset-id> \
  --wait

You can list presets and manage custom scenarios with arga test-runner scenarios ....

Custom scenarios

Create your own scenarios tailored to your application. There are two ways to define the twin data:

Natural language — describe what you want and Arga generates the seed configuration automatically
Explicit config — provide the exact JSON for each twin

When you use a natural-language prompt, Arga runs a two-pass pipeline to generate the seed configuration:

Twin selection — a classifier reads your prompt and picks the single most relevant twin. It always prefers provider-specific twins (slack, discord, notion, gmail, google_drive, google_docs, google_sheets, google_workspace, google_calendar, stripe, github, gitlab, dropbox, box, jira, salesforce, linear, postgres, unstructured) over unified. The unified twin is only selected when the prompt explicitly mentions “unified” or “unified.to”. Multiple twins are selected only when the prompt explicitly names more than one provider (for example, “a GitHub repo AND a Slack workspace”).
Config generation — a second pass generates the seed JSON scoped to the selected twin(s). Any secondary details that don’t map to the chosen twin’s schema are either mapped to the closest available field or omitted.

If you need full control over which twins are included, pass the twins array explicitly alongside your seed_config.

Choose a generation mode

Use Fast for everyday scenarios that should be ready sooner. Choose Thorough for stronger handling of complex requirements when a longer wait is acceptable. Fast is the default when you omit the option. The mode only affects generating new seed data from a prompt. Explicit seed JSON, saved scenarios, presets, and resets reuse their existing data. Changing the mode alone does not regenerate a saved scenario. To regenerate one, update its prompt without sending seed_config.

Interface	Create or regenerate a scenario	Generate data for a Twin Run
Web app	Fast or Thorough in the scenario editor	Fast or Thorough when entering a prompt
REST API	`generation_mode` on `POST /scenarios` or `PUT /scenarios/{scenario_id}`	`scenario_generation_mode` with `scenario_prompt` on `POST /twin-runs` or `POST /validate/twins/provision`
CLI	`--generation-mode fast` or `--generation-mode thorough` on scenario create, import, or update	The same flag on `arga twin-runs create`
Python SDK	`generation_mode="thorough"` on `client.scenarios.create(...)`	`scenario_generation_mode="thorough"` on `client.twins.provision(...)`
TypeScript SDK	`generationMode: 'thorough'` on `client.scenarios.create(...)`	`scenarioGenerationMode: 'thorough'` on `client.twins.provision(...)`
MCP	Use the REST API or CLI to save a scenario	`scenario_generation_mode: "thorough"` on `create_twin_run`

The API and MCP accept fast or thorough; unknown values are rejected. The Python and TypeScript SDKs export ScenarioGenerationMode for typed integrations. When provisioning with a scenario_id, Arga reuses that scenario and ignores the prompt and mode. For workflows that take a saved scenario ID, generate and save the scenario first, then pass its ID. See the CLI examples, MCP tool, Python SDK, and TypeScript SDK.

From the web app

Open Scenarios in the sidebar
Click Create Scenario
Enter a name and either a natural language prompt or raw JSON config
For a prompt, select Fast or Thorough
Save — Arga generates and stores the twin configuration

You can also save a Scenario while configuring a Twin Run, then reuse it later.

From a twin dashboard

Browser-facing twin UIs (Box, Discord, Dropbox, GitHub, GitLab, Gmail, Google Calendar, Google Drive, Linear, LinkedIn, Notion, Slack, Stripe, Unified, Unstructured) include a Save scenario button in the dashboard header. Clicking it captures the twin’s current state as a seed_config payload and hands it off to the Arga web app, which opens the scenario creation flow pre-filled with that configuration. Use it to turn a hand-crafted twin state into a reusable scenario without copying JSON manually.

From the API

With a natural language prompt:

curl -X POST https://api.argalabs.com/scenarios \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce checkout",
    "description": "Stripe with test customers and Slack with support channel",
    "prompt": "A Stripe account with 3 customers on different plans and a Slack workspace with a #support channel containing 10 recent messages about billing issues"
  }'

With explicit config:

curl -X POST https://api.argalabs.com/scenarios \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding flow",
    "twins": ["slack", "stripe"],
    "seed_config": {
      "slack": {
        "channels": [
          {"name": "general", "messages": [{"text": "Welcome to the team!", "user": "admin"}]}
        ]
      },
      "stripe": {
        "customers": [{"name": "Test User", "email": "test@example.com"}]
      }
    }
  }'

From the CLI

Create a scenario from a prompt:

arga test-runner scenarios create \
  --name "E-commerce checkout" \
  --prompt "Stripe with 3 customers and Slack with #support billing messages" \
  --twin stripe \
  --twin slack \
  --tag checkout

Import or export explicit seed JSON for agent-authored scenarios:

arga test-runner scenarios import --file scenario.json
arga test-runner scenarios export <scenario-id> --output scenario.json
arga test-runner scenarios update <scenario-id> --file scenario.json

Use a Scenario to seed a Twin Run:

arga previews twins provision \
  --twins stripe,slack \
  --scenario-id <scenario-id> \
  --wait

Managing scenarios

List

curl https://api.argalabs.com/scenarios \
  -H "Authorization: Bearer <api-key>"

Filter by twin or tag:

curl "https://api.argalabs.com/scenarios?twin=slack&tag=billing" \
  -H "Authorization: Bearer <api-key>"

Include presets alongside your scenarios:

curl "https://api.argalabs.com/scenarios?include_presets=true" \
  -H "Authorization: Bearer <api-key>"

Update

curl -X PUT https://api.argalabs.com/scenarios/<scenario-id> \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Updated description of the data I want"}'

If you update the prompt without providing a new seed_config, Arga regenerates the configuration from the updated prompt.

Delete

curl -X DELETE https://api.argalabs.com/scenarios/<scenario-id> \
  -H "Authorization: Bearer <api-key>"

Use a Scenario with twins

To start fresh twins from a Scenario, pass both twins and scenario_id to the Provision twins API:

curl -X POST https://api.argalabs.com/validate/twins/provision \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "twins": ["stripe", "slack"],
    "scenario_id": "<scenario-id>",
    "ttl_minutes": 60
  }'

Arga seeds the twins before the run becomes ready. Point your app or agent at the returned provider URLs, then run your tests against that software.

Persistent twin environments

A saved Scenario can also own a persistent twin environment. From the Twin Runs UI, choose a persistent session and a saved Scenario. Arga creates stable twin URLs that you can inspect, reseed from the Scenario, or tear down later. The API exposes create-or-get, status, reseed, and delete operations under /scenarios/{scenario_id}/twin-environment. The Python and TypeScript SDKs expose the same lifecycle through their scenarios resources.

Supported twins

Twin	What you can seed
`slack`	Channels, messages, threads, users, OAuth bot scopes, OAuth user scopes, custom tokens, tier (`free`, `pro`, `business_plus`, `enterprise`), disabled scopes, workspace constraints (file upload toggle, storage quotas, rate limits, message history limits, app install limits, workflow toggle)
`discord`	Guilds, channels, messages, members, boost level, file upload and emoji limits. Seed results include `guild_id` and `channel_ids` for referencing created resources.
`github`	Users, orgs, repos, files, branches, pull requests, merged PR refs, issues, labels, CI/status data, reviews, git references, branch protection, GitHub App configuration, default token scopes, disabled scopes
`gitlab`	Groups, projects, repository files, branches, issues, merge requests, pipelines, and hooks
`stripe`	Customers, products, prices, subscriptions, billing meters (with meter events)
`notion`	Pages, databases, blocks, workspace plan (`free`, `plus`, `business`, `enterprise`), disabled capabilities
`gmail`	Labels, messages, threads, and drafts
`google_drive`	Folders, files, storage tier (`free`, `basic`, `premium`, `ai_pro`), disabled scopes
`google_docs`	Documents with titles and body content
`google_sheets`	Spreadsheets, sheets, cell values, formulas, formatting, and developer metadata
`google_workspace`	People, contact groups, Workspace Events subscriptions, Apps Script projects, and Pub/Sub resources
`google_calendar`	Calendars, events
`jira`	Projects, issues, comments, worklogs, and webhooks
`salesforce`	Accounts, contacts, cases, and email templates
`box`	Folders, files
`dropbox`	Folders, files, account tier (`basic`, `plus`, `professional`, `business`)
`linear`	Teams, projects, cycles, issues, labels, and comments
`salesforce`	Accounts, contacts, cases, email templates, and email messages
`postgres`	Raw SQL statements applied to the mirrored data plane

Slack OAuth scope overrides

The Slack twin enforces OAuth scope requirements on API calls. You can customize the scopes granted to bot and user tokens by including oauth_bot_scopes, oauth_user_scopes, or tokens in the Slack seed configuration. This is useful for testing how your app handles missing permissions.

{
  "slack": {
    "channels": [{"name": "general"}],
    "oauth_bot_scopes": ["chat:write", "channels:read"],
    "oauth_user_scopes": ["search:read", "channels:read"],
    "tokens": [
      {
        "token": "xoxb-custom-token",
        "user_id": "UTWINBOT",
        "scopes": ["chat:write", "channels:read", "files:write"],
        "is_bot": true
      }
    ]
  }
}

Bot tokens always receive chat:write and files:write as minimum scopes, even if your configuration specifies a narrower set. See configurable token scopes for the full list of available scopes and their corresponding API methods.

Slack workspace constraints

You can configure workspace-level settings in the Slack seed to test how your app handles restricted environments — disabled file uploads, storage quotas, and rate limits.

{
  "slack": {
    "channels": [{"name": "general"}],
    "file_uploads_enabled": false,
    "max_storage_bytes": 5368709120,
    "storage_used_bytes": 5000000000,
    "rate_limiting_enabled": true,
    "rate_limits": {
      "files.getUploadURLExternal": {
        "window_seconds": 60,
        "max_requests": 5,
        "retry_after_seconds": 30
      }
    }
  }
}

Field	Type	Default	Description
`file_uploads_enabled`	`boolean`	`true`	Set to `false` to simulate a workspace with file uploads disabled. Returns a `file_uploads_disabled` error on upload attempts.
`max_storage_bytes`	`integer \| null`	`null`	Workspace storage quota in bytes. When set, uploads that would exceed the quota return a `storage_limit_reached` error.
`storage_used_bytes`	`integer`	`0`	Pre-existing storage usage in bytes. Combine with `max_storage_bytes` to simulate a nearly-full workspace.
`rate_limiting_enabled`	`boolean`	`false`	Whether per-method rate limiting is active.
`rate_limits`	`object`	`{}`	Map of Slack API method names to rate limit rules. Each rule specifies `window_seconds`, `max_requests`, and `retry_after_seconds`.

See workspace constraints for the full reference and error response shapes.

GitHub repository seed config

Each entry in the GitHub seed’s repos array creates one repository in the twin. You can describe the files inline with files, or clone a public GitHub repository to pre-populate the twin with its tracked files.

{
  "github": {
    "repos": [
      {
        "owner": "scenario-org",
        "name": "my-app",
        "repo_url": "https://github.com/octocat/Hello-World",
        "source_ref": "main",
        "branches": [{"name": "feature", "from": "main"}],
        "issues": [{"title": "Bug report", "body": "Something broke"}]
      }
    ]
  }
}

Field	Type	Description
`owner`	`string`	Org or user login that owns the seeded repo. When the owner matches a seeded org, the repo is created under that org; otherwise it is created under the authenticated user.
`name`	`string`	Repository name. If omitted, the name is derived from `repo_url` when a clone source is provided, otherwise it falls back to `repo-<index>`.
`repo_url`	`string`	Public HTTPS `github.com` repository URL or `owner/repo` shorthand. The runner shallow-clones the repo and seeds its tracked files into the twin. Aliases: `public_repo_url`, `clone_url`, `source_repo_url`.
`source_ref`	`string`	Branch or tag to clone from the public source repo. Falls back to `ref` when not set. Defaults to the source repo’s default branch.
`files`	`array`	Inline files to seed after any cloned files. When `repo_url` is set, `files` is only used if the field is explicitly present in the spec.
`branches`	`array`	Additional branches to create on the seeded repo.
`issues`	`array`	Issues to seed on the repo.
`private`, `default_branch`, `language`, `description`	various	Standard repository metadata.

When cloning from repo_url, the runner enforces these limits per repository to keep seeding fast and bounded:

Only public HTTPS github.com URLs are accepted. Credentialed URLs are rejected.
Up to 1,000 tracked files are copied.
Each file must be 1 MiB or smaller; symlinks are skipped.
The total cloned payload is capped at 25 MiB. Files beyond the limit are skipped.

Get started

Digital twins

Tests

Setup

Integrations

Resources

Preset scenarios

Functionality

Security

Edge cases

Using presets

Custom scenarios

Choose a generation mode

From the web app

From a twin dashboard

From the API

From the CLI

Managing scenarios

List

Update

Delete

Use a Scenario with twins

Persistent twin environments

Supported twins

Slack OAuth scope overrides

Slack workspace constraints

GitHub repository seed config

Tags

​Preset scenarios

​Functionality

​Security

​Edge cases

​Using presets

​Custom scenarios

​Choose a generation mode

​From the web app

​From a twin dashboard

​From the API

​From the CLI

​Managing scenarios

​List

​Update

​Delete

​Use a Scenario with twins

​Persistent twin environments

​Supported twins

​Slack OAuth scope overrides

​Slack workspace constraints

​GitHub repository seed config

​Tags

Preset scenarios

Functionality

Security

Edge cases

Using presets

Custom scenarios

Choose a generation mode

From the web app

From a twin dashboard

From the API

From the CLI

Managing scenarios

List

Update

Delete

Use a Scenario with twins

Persistent twin environments

Supported twins

Slack OAuth scope overrides

Slack workspace constraints

GitHub repository seed config

Tags