> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twins quickstart

> Set up digital twins for your staging environment in minutes

The `arga-wizard` CLI provisions [digital twins](/concepts/digital-twins) for your project and rewrites your environment config so your staging app talks to twins instead of real third-party APIs.

## Prerequisites

* **Node.js 18+** installed
* An **Arga API key** — either a quickstart key from [email signup](https://app.argalabs.com/get-started) (limited to 5 provisions) or a full-access key via `arga login` or from [Settings → API Keys](https://app.argalabs.com/settings/api-keys)

## Run the wizard

<Steps>
  <Step title="Launch the wizard">
    From your project directory:

    ```bash theme={null}
    npx arga-wizard
    ```

    Or if you already have the Arga CLI installed:

    ```bash theme={null}
    arga wizard
    ```

    The CLI version automatically passes your saved API key, so you skip the key prompt.
  </Step>

  <Step title="Select your twins">
    The wizard lists all available twins grouped by type. Pick the services your app integrates with.

    ```text theme={null}
    ? Which API twins do you need? (Space to select, Enter to confirm)
      -- UI Twins (with interactive dashboard) --
      [x] Discord          discord.com, api.discord.com
      [ ] Dropbox          api.dropboxapi.com
      [ ] GitHub           api.github.com, github.com, raw.githubusercontent.com
      [ ] Google Calendar  www.googleapis.com/calendar/v3
      [ ] Google Drive     www.googleapis.com/drive/v3
      [ ] Notion           api.notion.com
      [x] Slack            api.slack.com, slack.com
      [ ] Stripe           api.stripe.com
      -- Backend-only Twins --
      [ ] Box              api.box.com
      [ ] Jira             *.atlassian.net
      [ ] Linear           api.linear.app
      [ ] Salesforce       *.salesforce.com, *.force.com
      [ ] Waterfall        api.waterfall.io
      [ ] Unified          api.unified.to
      [ ] Unstructured     api.unstructuredapp.io
    ```

    **UI twins** have an interactive dashboard you can open in the browser to see messages, files, and other state. **Backend-only twins** respond to API calls but don't have a visual UI.
  </Step>

  <Step title="Review .env changes">
    The wizard scans your project for `.env` files and detects environment variables that match your selected twins.

    ```text theme={null}
    Detected changes for .env:
      SLACK_BOT_TOKEN=          ->  xoxb-F9SXMECOSFOGYR3XKXWN
      UNSTRUCTURED_API_KEY=     ->  test-unstructured-key
      DROPBOX_APP_KEY=y4pd...   ->  dropbox-twin-app-key

    ? Apply these changes? (Y/n)
    ```

    A backup is saved as `.env.arga-backup` before any changes are written.
  </Step>

  <Step title="Wait for provisioning">
    The wizard spins up ephemeral twin instances. This typically takes under a minute thanks to pre-warmed VMs.

    ```text theme={null}
    Provisioning twin instances...

      [1/2] Discord twin .......... ready
      [2/2] Slack twin   .......... ready

      Session expires in 10 minutes.
    ```
  </Step>

  <Step title="Start building">
    The wizard prints a summary with everything you need:

    ```text theme={null}
    ┌──────────────────────────────┐
    │  Arga Twins — Ready!                           │
    │                                                │
    │  Dashboard: https://app.argalabs.com/runs/...  │
    │                                                │
    │  Discord:  https://...--discord.sandbox....    │
    │  Slack:    https://...--slack.sandbox....      │
    │                                                │
    │  Session expires: 2026-03-28T14:00:00Z         │
    │                                                │
    │  Commands:                                     │
    │    arga wizard status    Check health          │
    │    arga wizard reset     Reset twin state      │
    │    arga wizard extend    Extend by 10 min      │
    │    arga wizard teardown  Destroy session       │
    └──────────────────────────────┘
    ```

    Start your app normally — all API calls to the selected services are now routed through twins.
  </Step>
</Steps>

## What the wizard does

Under the hood, the wizard:

1. **Validates your API key** against the Arga API (or reads it from `~/.config/arga/config.json` if you've run `arga login`)
2. **Provisions twin containers** on Arga's infrastructure via `POST /validate/twins/provision`
3. **Rewrites your `.env`** to replace real API tokens with twin-compatible defaults
4. **Creates minimal auth infrastructure** (tokens, bot users, root folders) so twins are ready to accept API calls — content is populated through [scenario seeding](/features/custom-scenarios)
5. **Writes a `.arga-session.json`** file that tracks the session for subsequent commands

## Available twins

<AccordionGroup>
  <Accordion title="Discord" icon="discord">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `discord.com`, `api.discord.com`, `discordapp.com`

    **Quickstart state:**

    * Server: "Default Server"
    * Users: `twin-bot` (bot)
    * Bot token: `fake-bot-token`
    * Channels, roles, members, and messages start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls

    **File uploads:** The Create Message endpoint accepts `multipart/form-data` requests with file attachments. Send files as `files[n]` or `file` form parts alongside a `payload_json` field (or a plain `content` field) and the twin records each upload as an attachment on the created message.
  </Accordion>

  <Accordion title="Slack" icon="slack">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `api.slack.com`, `slack.com`, `files.slack.com`

    **Quickstart state:**

    * Workspace: "Default Workspace"
    * Users: `slack-twin-bot` (bot), `slack-twin-user` (human)
    * Bot token: `xoxb-F9SXMECOSFOGYR3XKXWN`
    * User token: `xoxp-slack-twin-user-token`
    * OAuth client ID: `slack-twin-client-id`
    * OAuth client secret: `slack-twin-client-secret`
    * Default tier: `free` (1 GB max file upload, same as `pro`, `business_plus`, `enterprise`, and `paid` tiers; see the [admin API](/concepts/digital-twins#slack-twin-tier-limits) for tier details)
    * Channels start empty — populate them through [scenario seeding](/features/custom-scenarios) or the `conversations.create` API

    **OAuth support:** The Slack twin implements the OAuth 2.0 authorization code grant flow. Point your app's Slack OAuth URLs at the twin (via `SLACK_TWIN_BASE_URL`) to test "Add to Slack" install flows without hitting real Slack servers. The twin issues working `xoxb-`, `xoxp-`, and `xoxe.`-prefixed tokens that can be used for subsequent API calls.

    **Scope enforcement:** The twin enforces OAuth scope requirements on every authenticated API call. If a token lacks the required scope for a method, the twin returns a `missing_scope` error — matching real Slack behavior. You can [configure the scopes](/concepts/digital-twins#slack-twin-configurable-token-scopes) granted to bot and user tokens via scenario seeding to test permission edge cases.

    **Tier limits:** File uploads are subject to tier-based size limits. The twin starts on the `free` tier (1 GB cap — the same as paid tiers). Use the admin API to [switch tiers](/concepts/digital-twins#switching-tiers) (`pro`, `business_plus`, `enterprise`, or `paid`) to test tier-specific behavior. Each tier also controls message history limits, app install limits, and workflow availability.

    **Workspace constraints:** The twin supports workspace-level controls for [disabling file uploads, enforcing storage quotas, and simulating rate limits](/concepts/digital-twins#slack-twin-workspace-constraints). Configure these via scenario seeding or the admin API to test how your app handles restricted workspaces.

    **Multi-sender UI:** The inspector dashboard lets you post messages and add reactions as any user in the workspace via a sender picker, so you can test multi-user conversation flows without switching tokens manually.
  </Accordion>

  <Accordion title="Google Drive" icon="google-drive">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `www.googleapis.com/drive/v3`, `content.googleapis.com`

    **Quickstart state:**

    * Principals: Drive Twin Owner, Drive Twin Editor
    * Owner token: `ya29.drive-twin-owner`
    * Files and folders start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls
  </Accordion>

  <Accordion title="Dropbox" icon="dropbox">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `api.dropboxapi.com`, `content.dropboxapi.com`

    **Quickstart state:**

    * Root folder initialized — files and folders start empty
    * Populate content through [scenario seeding](/features/custom-scenarios) or API calls
  </Accordion>

  <Accordion title="GitHub" icon="github">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `api.github.com`, `github.com`, `raw.githubusercontent.com`

    **Quickstart state:**

    * Token: `ghp_test-github-twin-token`
    * Users, organizations, and repositories start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls

    **Supported resources:** Repositories, pull requests (with merge and reviewer requests), issues, branches (with protection rules), commits, check runs, check suites, git references, labels, pull request reviews, commit statuses, file contents (branch-aware), raw file downloads (`raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}` and `github.com/{owner}/{repo}/raw/{ref}/{path}`, served as public content without a bearer token and resolving slash-containing branch names), search, organizations, users, GitHub App endpoints (installations, access tokens, app metadata, and the manifest registration flow for creating multiple GitHub Apps at runtime), webhooks, and OAuth flows.

    **Scope enforcement:** The twin enforces OAuth scope requirements on API calls. Each route requires a specific scope (for example, `repo` for repository operations, `read:user` for user info). Parent scopes grant their children automatically — `repo` implies `repo:status`, `public_repo`, etc. Configure default token scopes via `default_token_scopes` and disable specific scopes via `disabled_scopes`. See [authentication handling](/concepts/digital-twins#authentication-handling) for details.

    **State export:** `GET /admin/state` returns a compact summary of the twin by default — schema version, seed, base/logical clocks, high-level counts, and a ready-to-use `seed_config.github` block that can recreate the same state in a new twin. The exported `seed_config.github` includes a per-repo `merged_prs` list of compact merged PR refs alongside the full `prs`/`pull_requests` arrays so merged PR history is preserved on replay. Pass `?full=1` (`GET /admin/state?full=1`) to get the deterministic, replay-oriented snapshot with repos, branches, PR aliases, per-PR changed files with decoded before/after code and patches, webhooks, and check runs. The dashboard's **Save scenario** button hands the compact `seed_config.github` payload to the Arga web app and creates a reusable scenario from it without requiring you to copy JSON manually — see [Save scenario from a twin dashboard](/features/custom-scenarios#from-a-twin-dashboard) for the equivalent flow on other twins.
  </Accordion>

  <Accordion title="Notion" icon="book">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `api.notion.com`, `notion.so`

    **Quickstart state:**

    * Workspace: "Notion Twin Workspace"
    * API key: `secret_notion-twin_seed`
    * Pages, databases, and users start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls
  </Accordion>

  <Accordion title="Stripe" icon="stripe">
    **Type:** UI twin (interactive checkout pages)

    **Intercepts:** `api.stripe.com`, `files.stripe.com`, `connect.stripe.com`, `mcp.stripe.com`

    **Quickstart state:**

    * All Stripe API v1 resources start empty (no seeded data by default)
    * Use the `/_twin/seed` endpoint to create a starter product, price, and webhook endpoint
    * API key prefix: `sk_test_` (any key with a valid prefix is accepted)

    **Supported resources:** Customers, payment methods, payment intents, setup intents, charges, refunds, disputes, subscriptions, invoices, invoice items, credit notes, products, prices, plans, coupons, promotion codes, tax rates, shipping rates, tokens, sources, payouts, balance, billing meters, meter events, meter event summaries, events, files, file links, checkout sessions, payment links, quotes, billing portal, subscription items, subscription schedules, usage records, tax IDs, webhook endpoints, mandates, and test clocks.

    **Browser pages:** The twin serves browser-facing pages for checkout, billing portal, a multi-page dashboard (`/dashboard` with home, payments, subscriptions, invoices, and balances pages), product catalog (`/products`), and customer management (`/customers`). Use these to inspect twin state visually during a run — the dashboard home shows revenue, MRR, active subscribers, and recent payments; the products page shows all products and their prices; the customers page shows customers with their subscriptions. You can also test end-to-end payment flows including success, card decline, and 3D Secure scenarios through the checkout pages.

    **Test cards:** Stripe-compatible test card numbers trigger specific outcomes (declines, 3D Secure challenges, processing errors) — matching the behavior of Stripe's own test mode.

    **Webhook delivery:** Register webhook endpoints via the API and the twin delivers signed events (`Stripe-Signature` header) to your application, just like the real Stripe.

    **Stripe MCP support:** The twin routes `mcp.stripe.com` and exposes a Stripe-compatible MCP JSON-RPC server at `POST /mcp` and `POST /mcp/v1`. OAuth discovery is served at `GET /.well-known/oauth-protected-resource`, `GET /.well-known/oauth-protected-resource/mcp`, and `GET /.well-known/oauth-authorization-server`. The server advertises the same 31 tools as the official Stripe MCP server (including `create_customer`, `list_customers`, `create_product`, `create_price`, `create_payment_link`, `create_invoice`, `list_subscriptions`, `update_subscription`, `cancel_subscription`, `create_refund`, `retrieve_balance`, `stripe_api_search`, `stripe_api_details`, `stripe_api_execute`, and others) and shares state with the Stripe API and Checkout surfaces. Use it from any MCP client or via the `@stripe/mcp` CLI bridge — requests without an `Authorization: Bearer <token>` header return `401`.
  </Accordion>

  <Accordion title="Box" icon="box">
    **Type:** Backend-only

    **Intercepts:** `api.box.com`, `upload.box.com`, `app.box.com`

    **Quickstart state:**

    * Enterprise: "Box Twin Enterprise" (ID: `11446498`)
    * Client ID: `box-twin-client-id`
    * Client Secret: `box-twin-client-secret`
    * Developer token: `box-developer-token`
    * Root folder and admin user created — files, sub-folders, and additional users start empty
  </Accordion>

  <Accordion title="Google Calendar" icon="calendar">
    **Type:** UI twin (interactive dashboard)

    **Intercepts:** `www.googleapis.com/calendar/v3`

    Calendar v3 API emulator with event CRUD operations. Calendars and events start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls.
  </Accordion>

  <Accordion title="Jira" icon="jira">
    **Type:** Backend-only

    **Intercepts:** `*.atlassian.net` (Jira Cloud REST API v3)

    **Quickstart state:**

    * Cloud site: `test-site.atlassian.net` (cloud ID `11223344-a1b2-3b33-c444-def123456789`)
    * OAuth client ID: `jira-twin-client-id`
    * OAuth client secret: `jira-twin-client-secret`
    * Webhook signing secret: `test-jira-webhook-secret`
    * Seeded metadata: priorities (`Highest`, `High`, `Medium`, `Low`, `Lowest`), statuses (`To Do`, `In Progress`, `Done`), issue types (`Task`, `Bug`, `Story`, `Epic`, `Subtask`), transitions, resolutions, and link types
    * Projects, issues, comments, worklogs, attachments, components, versions, filters, dashboards, groups, sprints, and boards start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls

    **Supported resources:** Issues (CRUD, bulk create, transitions, changelog, edit metadata, create metadata), projects, comments, worklogs, attachments, issue links, issue properties, votes, watchers, search and JQL search, users (`myself`, search, bulk, assignable, view-issue), components, versions, remote links, filters, dashboards, groups (and group members), fields, priorities, resolutions, statuses, status categories, issue types, server info, webhooks, and Agile endpoints (`/rest/agile/1.0/` boards, sprints, backlog).

    **API versioning:** Routes registered under `/rest/api/3/` are also reachable via the `/rest/api/2/` and `/rest/api/latest/` aliases, matching the real Jira Cloud REST API behavior.

    **ADF content:** Comments and issue descriptions are stored as [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/). Plain strings on input are auto-wrapped in a minimal ADF document so existing SDK calls continue to work.

    **OAuth and scope enforcement:** The twin implements the OAuth 2.0 authorization code grant flow at `/authorize` and `/oauth/token`. Every authenticated API call requires a `Bearer` token and is checked against the route's required scope. See [authentication handling](/concepts/digital-twins#authentication-handling) for details on default token scopes (`read:jira-work`, `write:jira-work`, `read:jira-user`, `manage:jira-project`, `manage:jira-webhook`, `manage:jira-configuration`), parent-child scope expansion, and disabling scopes for testing.

    **Webhook delivery:** Register webhook endpoints via `POST /rest/api/3/webhook` and the twin delivers signed events for issue and comment changes.

    **Admin endpoints:** `GET /admin/state`, `POST /admin/reset`, `POST /admin/clock` (advance the twin's clock by `seconds`), `GET /admin/stub-hits`, and `POST /admin/stub-hits/clear`.
  </Accordion>

  <Accordion title="Linear" icon="list-check">
    **Type:** Backend-only

    **Intercepts:** `api.linear.app`, `linear.app`

    **Quickstart state:**

    * GraphQL endpoint ready at `POST /graphql`
    * Default personal API key: `lin_api_twin_owner_personal_key_0001` (sent in `Authorization` with no `Bearer` prefix)
    * Teams, projects, cycles, issues, labels, comments, tokens, and webhooks start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls

    **Supported resources:** GraphQL queries and mutations for teams, projects, cycles, issues, labels, comments, workflow states, users, organization, and webhooks. Built to match the schema documented at [Linear's GraphQL reference](https://linear.app/developers/graphql) and the wire-level behavior of the [`@linear/sdk`](https://www.npmjs.com/package/@linear/sdk) client.

    **Authentication:** Personal API keys are sent in `Authorization` without a `Bearer` prefix. OAuth 2.0 tokens are sent as `Authorization: Bearer <token>` and issued through `GET`/`POST /oauth/authorize`, `POST /oauth/token`, and `POST /oauth/revoke`, with scope enforcement and refresh tokens.

    **SDK compatibility:** Responses include `__typename` on every entity, relations are returned as `{ id }` in default selections, and error envelopes surface `extensions.type` values the SDK dispatches on (`"authentication error"`, `"invalid input"`, `"ratelimited"`, `"feature not accessible"`).

    **Webhook delivery:** Register subscriptions via `POST /admin/webhooks`. Deliveries include `Linear-Signature` (lowercase-hex HMAC-SHA256), `Linear-Delivery`, `Linear-Event`, and `Linear-Timestamp` headers. Inspect, flush, and replay through `/admin/webhook-events` and `/admin/webhook-deliveries`.

    **Admin endpoints:** `GET /admin/state`, `GET`/`PUT`/`PATCH /admin/config`, `POST /admin/reset`, `POST /admin/clock/advance`, `POST`/`DELETE /admin/webhooks`, `GET /admin/webhook-events`, `GET /admin/webhook-deliveries`, `POST /admin/webhook-events/flush`, `POST /admin/webhook-events/{id}/replay`, and `GET /admin/fidelity`.
  </Accordion>

  <Accordion title="Salesforce" icon="cloud">
    **Type:** Backend-only

    **Intercepts:** `login.salesforce.com`, `test.salesforce.com`, `*.salesforce.com`, `*.force.com`, `*.my.salesforce.com`

    **Quickstart state:**

    * Access token: `00D000000000001!salesforce-twin-token`
    * Instance URL: `http://twin-salesforce:8080` (replaced with the sandbox URL at provision time)
    * REST discovery, sObject CRUD, query/search, composite, and limits endpoints ready under `/services/data/v{version}/`
    * Accounts, contacts, cases, email templates, email messages, and users start empty — populate them through [scenario seeding](/features/custom-scenarios) or API calls

    **Supported resources:** sObject CRUD for Accounts, Contacts, Cases, EmailTemplates, EmailMessages, Users, and related standard objects (including `describe`, `describe/layouts`, `describe/compactLayouts`, `listviews`, relationship traversal, and updated/deleted feeds), SOQL (`/query`, `/queryAll`, `/query/{locator}`), SOSL (`/search`, `/parameterizedSearch`, `/search/scopeOrder`, `/search/layout`), composite endpoints (`/composite`, `/composite/batch`, `/composite/graph`, `/composite/tree/{sobject}`), Bulk API v2 job shells (`/jobs/query`, `/jobs/ingest`), invocable actions (`/actions`, `/actions/standard`, `/actions/custom`) for case creation and email-template send flows, and a Tooling API surface for sobjects, queries, and basic discovery.

    **Authentication:** OAuth 2.0 token exchange at `/services/oauth2/token` (and `/oauth2/token`), `userinfo` at `/services/oauth2/userinfo`, identity URLs at `/id/{org_id}/{user_id}`, and bearer-token authentication on every API call.

    **Admin endpoints:** `POST /admin/reset`, `GET /admin/state`, `POST /admin/clock`, plus a liveness check at `GET /healthz` (also `GET /health`).
  </Accordion>

  <Accordion title="Waterfall" icon="droplet">
    **Type:** Backend-only

    **Intercepts:** `api.waterfall.io`

    **Quickstart state:**

    * Starts empty by default
    * API key: `ad18e456-0dd7-45e1-b094-43a0361aedfa`
    * Supports company search, people search, enrichment, verification, and account endpoints
  </Accordion>

  <Accordion title="Unified" icon="arrows-to-dot">
    **Type:** Backend-only

    **Intercepts:** `api.unified.to`, `unified.to`

    Creates Unified.to integration connections that proxy to Slack, Google Mail, Google Drive, Google Calendar, Box, Notion, and Dropbox. Use this twin only when your app talks to Unified.to directly. For actual provider data (channels, files, pages, repos, etc.), use the provider-specific twin instead.
  </Accordion>

  <Accordion title="Unstructured" icon="file-lines">
    **Type:** Backend-only

    **Intercepts:** `api.unstructuredapp.io`, `platform.unstructuredapp.io`

    **Quickstart state:**

    * Partition endpoint ready at `/general/v0/general`
    * Jobs endpoint ready at `/api/v1/jobs/`
    * API key: `test-unstructured-key`
    * Workflow templates start empty — populate them through [scenario seeding](/features/custom-scenarios)
  </Accordion>
</AccordionGroup>

## Environment variables

The wizard recognizes these environment variables per twin and replaces them with twin-compatible defaults:

| Twin            | Variables the wizard detects                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Discord         | `DISCORD_TOKEN`, `DISCORD_BOT_TOKEN`                                                                                      |
| Slack           | `SLACK_BOT_TOKEN`, `SLACK_TOKEN`, `SLACK_SIGNING_SECRET`, `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_TWIN_BASE_URL` |
| Stripe          | `STRIPE_SECRET_KEY`, `STRIPE_API_KEY`, `STRIPE_TWIN_BASE_URL`, `STRIPE_TWIN_WEBHOOK_SECRET`                               |
| Google Drive    | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_ACCESS_TOKEN`                                                         |
| Dropbox         | `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`, `DROPBOX_ACCESS_TOKEN`                                                           |
| Notion          | `NOTION_API_KEY`, `NOTION_TOKEN`                                                                                          |
| Box             | `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET`, `BOX_DEVELOPER_TOKEN`                                                               |
| Google Calendar | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`                                                                                |
| Jira            | `JIRA_BASE_URL`, `JIRA_HOST`, `JIRA_CLIENT_ID`, `JIRA_CLIENT_SECRET`, `JIRA_API_TOKEN`                                    |
| Linear          | `LINEAR_API_KEY`                                                                                                          |
| Salesforce      | `SALESFORCE_ACCESS_TOKEN`, `SALESFORCE_INSTANCE_URL`                                                                      |
| Waterfall       | `WATERFALL_API_KEY`, `WATERFALL_API_BASE_URL`, `WATERFALL_API_URL`, `WATERFALL_BASE_URL`                                  |
| Unstructured    | `UNSTRUCTURED_API_KEY`                                                                                                    |
| Unified         | `UNIFIED_API_KEY`                                                                                                         |

Variables not associated with a selected twin are left untouched. The original file is always backed up to `.env.arga-backup`.

## Session management

Twin sessions are ephemeral and expire after 10 minutes by default. Use these commands from your project directory:

```bash theme={null}
# Check if your twins are still running
arga wizard status     # or: npx arga-wizard status

# Reset all twins to their initial empty state
arga wizard reset      # or: npx arga-wizard reset

# Add another 10 minutes to the session
arga wizard extend     # or: npx arga-wizard extend

# Tear down immediately and clean up
arga wizard teardown   # or: npx arga-wizard teardown
```

Session state is stored in `.arga-session.json` in your project root. Add it to your `.gitignore`.

## Inspect twin session logs

If twin provisioning stalls or something in the sandbox environment behaves unexpectedly, inspect the run logs from your project directory:

```bash theme={null}
arga runs logs
arga runs logs --errors-only
arga runs logs --json
```

Because the wizard writes `.arga-session.json`, `arga runs logs` can resolve the active run automatically from that directory.

These logs are mostly about the twin/sandbox environment rather than your app's own application logs. They include worker logs for build, deploy, and warm-up jobs plus runtime logs from the services Arga uses to provision and route the sandbox. Use `--errors-only` when you want a faster view of failed worker jobs and warning/error runtime entries.

For the full CLI reference and response shape, see [CLI](/cli-and-mcp) and [Get run logs](/api-reference/get-get-run-logs).

## Re-run just the .env step

If you need to update your `.env` without re-provisioning:

```bash theme={null}
arga-wizard env
```

This re-runs twin selection and .env rewriting without spinning up new instances.

## Restoring your original .env

To revert to your original environment variables:

```bash theme={null}
cp .env.arga-backup .env
```

## Next steps

<CardGroup cols={2}>
  <Card title="Digital twins" icon="clone" href="/concepts/digital-twins">
    Learn how twins intercept API calls and maintain state.
  </Card>

  <Card title="Twin reference" icon="list-checks" href="/concepts/twin-reference">
    See support, limitations, and MCP tools for every twin.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli-and-mcp">
    Full CLI reference including authentication and validation commands.
  </Card>

  <Card title="MCP" icon="plug" href="/mcp">
    Install Arga context tools into your IDE agent.
  </Card>
</CardGroup>