Patterns that work

How to prompt an AI agent working in an agentry sandbox so it produces apps that actually ship.

The patterns below come from looking at what AI agents do well in agentry sandboxes — and what they reliably miss without a nudge. They apply across harnesses (Claude Code, Cursor, Roo, Continue) and across model providers.

Open with "Use agentry"

The single most important word in your first prompt is agentry. Harnesses (Claude Code, Cursor, Roo, Continue) all support multiple toolsets at once — without a nudge, they'll write code into your local repo by reflex. Saying "Use agentry to…" pushes them toward the MCP tools that build inside a sandbox.

A good opener is:

Use agentry to build me <thing>.

It should <key capability 1> and <key capability 2>.

Why this works:

1. "Use agentry" routes the work into a sandbox. Skip it and the harness will scaffold files next to your existing project — no sandbox, no preview URL, no deploy path.
2. It names what you want, not how to build it. Models do their best work when asked for outcomes, not steps.

Example:

Use agentry to build me a personal landing page with a waitlist signup form. It should collect emails into a list I can export, and look minimal-but-polished.

Don't pin a framework unless you have to

The sandbox is opinionated — there's a preferred stack baked in for web apps so the agent doesn't have to negotiate one. Telling the agent "use Next.js" or "use Vite + React" overrides those defaults and tends to drag the build into less-paved paths (broken devserver wiring, mismatched build commands, deploy preflights that fail).

Leave the stack out. Describe what you want; let the sandbox pick.

If you genuinely need a specific framework — say, an Astro static site or a Python service — name it explicitly. Otherwise the default path is the smoother one.

Let the agent name the sandbox

Don't pre-pick a sandbox name. Models do better when they pick a descriptive name themselves (waitlist-landing, pocket-tracker, recipe-app), and agentry auto-suffixes if there's a collision so you don't lose work.

Why this matters

If you say "call the sandbox app", and you have another running sandbox called app, agentry will auto-allocate app-7f2a to keep them isolated — but the agent might then refer back to app in follow-up tool calls, which won't exist. Letting the agent pick a unique-feeling name avoids that confusion entirely.

Iterate inside one sandbox per project

A single project — even one you spend weeks on — should live in one sandbox. The same conversation should use the same sandbox_id for every tool call.

Why: file state, dependency state, env, port assignments, project manager state — all of it lives in that sandbox. Switching sandboxes mid-project means lost work.

Concrete:

• Don't open a new chat per task. Open a new chat per project.
• Within a chat, follow up with "now add X" or "fix the bug in Y", not "start over and build X".
• If you do need to restart, ask the agent to delete the old sandbox first.

Previewing your work

The agent does not hand you a URL when it's done. Sandboxes don't auto-expose ports — that's a deliberate choice so nothing leaks until you ask.

To look at what was built, open app.agentry.run/sandboxes, pick your sandbox, find the listening port, and click Share. The dashboard gives you a *.agentry.live preview URL you can open yourself or send to someone for feedback. The preview tracks the sandbox as the agent makes changes.

Test what you can see

If you can open the URL, the most useful test is to actually click around. "Looks good in the preview" beats "passes tsc" for catching real-world issues.

Specific things to spot-check:

• Does the page render at all? (catches build / SSR errors)
• Do forms submit? (catches API route wiring)
• Do hot links work? (catches routing errors)
• Does the styling match what you asked for? (catches model misreading the prompt)

If something's wrong, paste a screenshot or describe the issue concretely. "The submit button doesn't do anything" beats "the form is broken".

Build it before saying done

This one is so important it's worth its own header.

Have the agent run the project's production build before you call a task finished — it's the strongest signal you can get that the project is actually shippable. It catches what the dev server happily ignores:

• TypeScript errors that next dev tolerates
• Missing imports that show up only on a full compile
• Stale type references after refactors
• Bad config that loads at build time but not in dev

Always close a working session with:

Run the production build and tell me if it passes.

If it fails, the agent reads the error, fixes the file, and builds again. Repeat until it's clean. The Deploy button re-runs this exact build as a backstop, so a clean build here means a smooth deploy.

Bind services before, not after

If your project needs MongoDB, Postgres, an AI key, or any other service — bind it on your server before asking the agent to build.

agentry service bind mongodb

Now every new sandbox gets MONGODB_URL in its env. The agent's code can read it directly. No setup back-and-forth.

If you skip this and bind later, the agent will already have written its own setup logic (a local mongodb-memory-server, or a placeholder URL). You'll either have to re-prompt for a refactor or live with the wrong setup.

See Add a database for the bind flow.

Refer to files by relative path

When pointing the agent at a specific file, use the relative path from /workspace:

Fix the type error in src/lib/db.ts.

Not "fix that database file you wrote earlier". Models can lose the thread on file references after a few turns; a path is unambiguous.

When you want to deploy, deploy from the dashboard

The dashboard's Deploy button is intentionally the shipping surface — not an MCP tool. You can ask the agent for status:

Is the preview working as I expect? If so, I'm going to deploy.

But the click is on you. This is a deliberate division of labor: AI builds and verifies, human ships. The Deploy button's preflight is a hard backstop that re-runs the build on your behalf.

When something doesn't work

The single most useful thing you can do is paste the error verbatim into the chat:

When I run the dev server I get:

Error: connect ECONNREFUSED 127.0.0.1:27017

Fix it.

The agent reads the error and reasons about it. Vague reports ("it's broken") force the agent to guess; specific errors let it solve.

Avoid one-shot mega-prompts

Don't ask for a 30-feature app in a single turn. Even with strong models, you'll get a half-built version of most features and a working version of none.

Better:

1. First turn: scaffold the project + the home page.
2. Open the preview. Confirm it looks right.
3. Second turn: add the next feature.
4. Repeat.

You ship faster, the agent recovers from mistakes faster, and the agent's context stays focused.

Anti-pattern signals to watch for

If you see these in the agent's output, something's drifting. Push back early:

What you see	What's actually happening	What to do
"Let me start by setting up a virtual environment for our React app"	Confused stack	Re-anchor to the sandbox default: "Use the sandbox's default web stack."
"I'll create a project in /tmp/..."	Working outside /workspace	"Work in /workspace/projects/<name>."
Multiple short command_run calls retrying npm install with different flags	Hit a quoting bug	Suggest writing package.json first via file_write, then running plain npm install.
"I created a mock database since none was configured"	Should have bound a service	Abort the build, run agentry service bind <db> on your server, re-prompt.
Agent never calls the build	Skipping the final check	Ask: "Run the build and report."

Next

• Mistakes to avoid — anti-patterns we see hourly.
• Examples — real prompts that shipped real apps.
• Ship an app — the deploy flow.