---
title: Execution Runtime
description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations
---

This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, what observability data you can access, and the hard limits enforced on all executions.

---

## Execution Lifecycle

### The Four Stages

Every execution traverses four stages: trigger, route, execute, and return.

1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.

### Concurrency Model

Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:

- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.

### Timeout Enforcement

Timeouts are enforced by the platform. You do not handle them explicitly in your code:

- **Default timeout:** A platform default of 2 hours applies to all resource types unless overridden. This is a safety-net ceiling for runaway executions, not a target -- run long work with `--async` and observe via SSE/polling rather than holding a synchronous call open.
- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.

### Cancellation

Cancellation is initiated by the platform and requires no special code in your handler. The worker is terminated immediately and the execution is recorded as `failed` with a cancellation reason (there is no separate `cancelled` status).

**What triggers cancellation:**

- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
- The platform timeout expires
- The resource is deleted while an execution is in-flight

---

## Error Handling

### How Errors Reach You

Errors are displayed depending on the surface you use to inspect them:

- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.

### What Causes a Failed Execution

- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
- **Cancellation:** The worker is terminated and the execution is marked `failed` with a cancellation reason.

---

## Observability

### Logging

You produce logs using standard `console` methods -- no special logger object is needed:

- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.

### Log Transport

Logs are delivered to the platform atomically with the execution result:

- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.

### Log Retention and Display

- **Retention:** 30 days by default (configurable per plan).
- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.

---

## Resource Lifecycle

### Status

Every resource on the platform has a status that you control in your definition:

- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.

### Versioning

v1 versioning is intentionally simple:

- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.

### Deletion

- **Via CLI:** Remove the resource from your `DeploymentSpec` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.

---

## Resource Limits & Quotas

### Per-Worker Limits

Limits enforced per worker thread at runtime:

| Resource         | Value                                                       |
| ---------------- | ----------------------------------------------------------- |
| Memory (V8 heap) | 256MB per worker                                            |
| Disk             | Bundle file only (ephemeral, not persistent across deploys) |

- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.

### Scale Limits

Hard limits to prevent abuse and ensure platform stability:

| Limit                  | Value                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| Max execution duration | 2 hours (platform default for all resource types; agents override via `constraints.timeout`) |
| Max log volume         | 100MB/day                                                                                    |
| Max deploy frequency   | 60/day                                                                                       |

- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).

### Networking

- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.

---

## v1 Limitations

| Limitation                                      | Reason                                                                                                                                                                                           | Future path                                                                                                             |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions.                                                                        | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
| **No streaming logs**                           | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker.                                                                   | SSE/WebSocket push from external processes to the platform log system.                                                  |
| **Static resource priority conflicts**          | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message.                                                   |

---

## Organization Provisioning

Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.

---

**Last Updated:** 2026-03-06
