Sandboxes

Overview

A sandbox is a private, tenant-scoped workspace where you develop an app of your own against Veltrix before it is installed. You write the app on your machine, the Veltrix CLI syncs it into the sandbox, and the portal validates the manifest, lets you edit files in the browser, runs the app's handlers in an isolated process, and previews its UI. Code in a sandbox is visible only to your organization, and a sandbox that stops being used expires automatically.

Sandboxes are for app authors. They are not where you manage security configurations; for that see Configuration Canvas. For how to write an app, see App Development.

Availability

• Sandboxes are an operator-controlled feature. When they are on for your deployment, Sandboxes appears in the sidebar under Operate (/sandboxes).
• When they are off, the sidebar item is hidden, and opening the page shows "Sandboxes are not enabled" and asks you to contact your Veltrix administrator.

Creating a sandbox

The portal lists, inspects, edits and deletes sandboxes, but a sandbox is created from the CLI.

1. Create an API key in Settings, Keys & Tokens that is authorized for sandboxes: either it carries the sandbox:write scope (plus sandbox:execute if the CLI should run handlers), or it is bound to a role that grants sandbox access, such as an administrator role. See API Keys & Tokens.
2. Sign in and create a sandbox for the app you are building, then start the dev loop:

veltrix login
veltrix sandbox create my-sandbox --app <app-id>
veltrix dev ./my-app --sandbox my-sandbox

• The sandbox name and the app id must be lowercase letters, digits and hyphens, up to 64 characters, and start and end with a letter or digit.
• Sandbox names are unique within your organization.
• Every successful sync renews the sandbox's expiry.

The empty states in the portal show this same three-line snippet.

The sandbox list

The Sandboxes page lists every sandbox in your organization, newest first.

Delete removes the sandbox and its synced files after a confirmation. Your local files are not affected, and you can recreate the sandbox with the CLI. Refresh reloads the list.

Statuses

Manifest, files and the editor

Open a sandbox to see its detail page: the header (name, status, app, last sync, expiry, the dev command with a copy button, Refresh and Delete), then four cards. The page updates live when the CLI syncs or when a peer edits a file.

Manifest

• Before the first sync it shows "Not synced yet" and the CLI snippet.
• After a sync it shows the app's App ID, Name and Version, and a validation banner: Valid with the number of server sources transpiled, or Invalid with the list of errors. Warnings are counted and listed.
• Below it is the list of Configuration types, each with its id and a badge for every handler it declares (validate, deploy, rollback, healthCheck, driftDetect, getStatus).

Add configuration type

The button appears once the sandbox has synced. It scaffolds a new configuration type and adds it to the manifest.

It creates config-types/<id>/ with canvas.yaml, defaults.yaml and the six handlers (validate, deploy, rollback, healthCheck, driftDetect, getStatus), and the new files sync down to your local workspace.

Files and the in-browser editor

• The file list shows each synced file with its size and a short hash, and loads more on request.
• Selecting a file opens it in a code editor. Save (or Ctrl/Cmd+S) writes it, re-validates the manifest and renews the expiry. TypeScript files are transpiled again on save. Deleting a file asks for confirmation.
• Binary files, and text files larger than 256 KB, open read-only.
• If the file changed since you opened it, the save is refused as a conflict and a banner explains it. If the CLI changes the open file while you have unsaved edits you get the same warning; if you have no unsaved edits the file reloads on its own.
• After a save you see whether the manifest is still valid.

Uploads are checked on the way in: paths must stay inside the sandbox, executable file types and links are rejected, names starting with .veltrix are reserved, and there are caps on file count and total size.

Running checks

The Checks card runs your app's handlers against a draft so you can see them work before you ship.

• Run all checks runs every runnable handler each configuration type declares, one after another: validate, healthCheck, driftDetect and getStatus. Each line goes from pending to running to success or failure, with its output. If the whole sandbox is unavailable (never synced or syncing, expired, or too many concurrent runs) the remaining checks are skipped.
• Run a single handler: pick a configuration type and one of its handlers, then Run handler. The run uses an empty draft canvas, so no field values are supplied.

A run result shows pass or fail, the handler's return value, duration, whether it timed out, and the console output the handler produced.

What runs, and what cannot

• deploy and rollback are never run, because they change external systems.
• Each run executes in an isolated child process with a scrubbed environment, a memory cap (256 MB by default) and a hard time limit (30 seconds by default). Each organization can run a limited number of handlers at once (two by default); extra requests are refused with a 429.
• The environment is always named "sandbox". healthCheck and driftDetect may only target components you have tagged sandbox, and only use a credential tagged sandbox for the same tool. Production credentials are unreachable.
• Handlers cannot reach the database or platform secrets. The connectivity provider is not available to sandbox runs.
• Running handlers requires a status of Active. The card explains why when it is Syncing, Error or Expired.

Previewing the app's UI

If the manifest declares a client entry and at least one page with nav: sidebar, the Preview card renders the app's pages inside the portal, the way an installed app would look, with a page switcher.

• Preview is read-only. A change the page tries to save is blocked, and a notice says "Sandbox preview is read-only — the change to <path> was not saved."
• Permission requirements declared on pages are not enforced in preview, so you can see every page.
• Empty states tell you what is missing: "Nothing to preview yet" (never synced), "This app doesn't declare a client UI", or "No page-switcher pages declared". A page whose component is not exported by the client bundle shows "Page unavailable".
• A runtime error in a page is contained and shown instead of breaking the portal.

Limits, permissions and gotchas

The quota is per developer, not per organization. In the CLI a developer is identified by the API key, so give each person their own key; people who share one key share one quota. In the portal the developer is the signed-in user.

Permissions

Gotchas

• There is no "create" button in the portal; use veltrix sandbox create.
• If a sandbox shows Expired, its files are gone. Delete it and create a new one, then sync again from your local copy.
• An Error status after a sync means the manifest or sources failed validation. Open the Manifest card for the exact errors.
• Sandbox runs execute against a draft, not your real deployed configurations. Do not expect them to see live production state.