Prerequisites
- A Blaxel account and workspace with permission to create sandboxes
- Herdr
0.8.0or newer on macOS or Linux - Node.js
22or newer, with npm and Git available locally - The Blaxel CLI installed locally; this walkthrough is verified with
0.1.110 - Access to Codex through an account or an
OPENAI_API_KEYfor the agent running inside the sandbox
1. Install the plugin and connect to Blaxel
Log in to Blaxel and check your active workspace:2. Configure the agent and previews
Open the dashboard and presst to choose Codex, Claude Code, OpenCode, or Pi. Press w to choose the workspace for new sandboxes. Existing sandboxes keep their original tool and workspace.


config.json in that directory. Keep any existing settings you need and set:
blaxel/ts-app:latest sandbox with 4096 MB of memory, and a seven-day idle deletion policy by default. Set workspace to a workspace name if you need a fixed target for new sandboxes. Existing mappings keep the workspace they were created in.
For agent authentication, complete the Codex login inside the sandbox when prompted. If OPENAI_API_KEY is already available to the Herdr process, the plugin passes it as an encrypted sandbox secret and signs Codex in with it. It does not copy local coding-agent sessions or credential files.
Keep credentials out of
config.json and agentArgs. The configuration reference also covers Claude Code, OpenCode, Pi, regions, upload limits, and expiration settings.3. Prepare the invoice project
Clone the plugin repository to get its runnable example, then copy only the example into a fresh Git worktree:pwd as a workspace in Herdr. Use a local shell pane in that workspace for the plugin commands below.
4. Start an agent in Blaxel
Run Start from the invoice project’s local Herdr pane:.git, dependencies, environment files, common credentials, and recognized secrets from the upload.
Each Start creates an independent sandbox, including repeated Starts from the same pane. To return to an existing sandbox, use Connect in the dashboard.
Open the dashboard from a local Herdr shell:
Enter or c to connect to its agent pane.


5. Update and test the invoice summary
Give the remote agent this task:overdueCents: 84550, and all tests should pass. The edits remain in the sandbox until you approve applying them locally.
6. Reconnect to the same session
Close the Blaxel agent pane. Open the dashboard again from a local Herdr shell:Enter or c. The plugin reattaches to its persistent remote tmux session. Ask the agent to run npm test again and confirm that its changes are still present.
The dashboard selects the exact sandbox even when the project has several agents. Local herdr commands run in your local shell pane; the agent pane runs inside the sandbox.
7. Open a private application preview
The invoice example starts as a command-line program. To view its result through a browser, ask the remote agent to createserver.mjs with this content:
node server.mjs, keep it running, and verify http://127.0.0.1:3000/ from inside the sandbox. The server must listen on 0.0.0.0 for Blaxel to route preview traffic to it.
If Codex requests permission to bind the port or make a local HTTP request, review and approve that command in the remote agent pane.
In the local Herdr dashboard, select the same sandbox and press p for Previews. Open the temporary URL shown for port 3000. Your browser should display the JSON summary, including the overdue balance.
Keep
publicPreviews set to false. The plugin generates a private preview token valid for ten minutes; reopen Previews to obtain a new link when it expires. Treat that temporary URL as a credential.8. Review and apply the changes locally
Ask the agent to showgit diff and finish any file edits before applying. In the local dashboard, select the sandbox and press a for Apply.
The plugin exports the remote changes against the upload baseline, checks the patch against your current local files, and shows the complete patch with colored additions and deletions. Use Page Up and Page Down to review it, then answer y to apply or press Escape to cancel. Exports larger than 1 MiB are refused before download or local changes; reduce the remote changes before retrying.


overdueCents is 84550, the tests pass, and server.mjs is present. If a local change conflicts with the remote patch, the plugin applies nothing. Resolve or stash the conflicting local edits, then retry Apply.
9. Delete the sandbox
After verifying the local changes, select the example’s sandbox in the dashboard and pressd for Delete. Check the sandbox name in the confirmation and type DELETE to permanently remove it.
Refresh the dashboard and confirm that the mapping is gone. If you started more than one sandbox for the exercise, delete each one you no longer need.
Troubleshooting
Resources
Herdr Blaxel plugin and example
Read the plugin reference and run the invoice summary example.
Private sandbox previews
Learn how preview URLs and access tokens connect your browser to a sandbox application.
Sandbox expiration
Configure lifetime and idle deletion policies for your sandboxes.
