Configure an agent

An agent is a named worker with instructions, tools, devices, memory, connected accounts, and approval rules. The goal is to make the agent predictable enough to trust, but capable enough to do real work inside MIOSA sandboxes and computers.

Configuration checklist

Identity

Use a focused name and description.

Good:

Name: Landing Page Builder
Description: Builds, previews, and publishes branded Next.js landing pages.

Weak:

Name: Helper
Description: Does stuff.

Agents are easier to delegate to when their job is specific.

Visibility

Workspace agents should never silently inherit every personal connection in the workspace. Attach only the accounts and tools they need.

Instructions

Instructions should include:

• the agent’s role
• the expected output
• where work must happen
• what tools it may use
• what requires approval
• what counts as done

Example:

You are a Next.js build agent.
Work only inside the assigned MIOSA sandbox at /workspace.
Write files directly into the sandbox.
Run npm install, npm run lint, and npm run build before returning.
Expose port 3000 for preview.
Create artifacts for screenshots and generated reports.
Ask for approval before publishing or creating extra child sandboxes.

Model and runtime

MIOSA can support several runtime shapes:

The runtime should be a configuration value, not hard-coded into product logic. Your product can choose the default runtime per agent type and still allow advanced users to supply custom runtimes later.

Runtime profiles

For white-label products, configure default runtimes at the tenant or workspace level instead of repeating the same connector and env setup for every sandbox.

miosa agent-runtime-profiles create 
  --name "Default app builder" 
  --runtime claude-code 
  --tools files,exec,previews,artifacts 
  --connectors refero/design-research,anthropic/workspace-claude 
  --policy '{"approval":"confirm-risky","max_child_sandboxes":5}' 
  --default 
  --json

await miosa.agentRuntimeProfiles.create({
  name: "Default app builder",
  runtime: "claude-code",
  tools: ["files", "exec", "previews", "artifacts"],
  connectors: ["refero/design-research", "anthropic/workspace-claude"],
  policy: { approval: "confirm-risky", max_child_sandboxes: 5 },
  isDefault: true,
})

client.agent_runtime_profiles.create(
    name="Default app builder",
    runtime="claude-code",
    tools=["files", "exec", "previews", "artifacts"],
    connectors=["refero/design-research", "anthropic/workspace-claude"],
    policy={"approval": "confirm-risky", "max_child_sandboxes": 5},
    isDefault=True,
)

Use profiles for defaults. Use miosa sandbox prompt or the Agent Runs API for individual task dispatch.

When a default profile exists, every new sandbox or cloud computer in that tenant/workspace gets the profile automatically unless the caller opts out. MIOSA applies the profile before the runtime is inserted:

# Uses the workspace or tenant default profile automatically.
miosa sandbox create --template nextjs --name builder --timeout 1h --wait

# Force a specific profile for this sandbox.
miosa sandbox create 
  --template nextjs 
  --agent-profile 9f4b3d8e-0000-0000-0000-000000000000 
  --wait

# Create a clean sandbox with no default runtime profile.
miosa sandbox create --template node --skip-agent-profile

# Create a browser/desktop computer with the workspace default profile.
miosa computers create --name browser-worker --workspace ws_123

# Force a specific profile for one computer.
miosa computers create 
  --name browser-worker 
  --agent-profile 9f4b3d8e-0000-0000-0000-000000000000

const sandbox = await miosa.sandboxes.create({
  templateId: "nextjs",
  agentRuntimeProfileId: "9f4b3d8e-0000-0000-0000-000000000000",
})

const computer = await miosa.computers.create({
  name: "browser-worker",
  agentRuntimeProfileId: "9f4b3d8e-0000-0000-0000-000000000000",
})

sandbox = client.sandboxes.create(
    template_id="nextjs",
    agent_runtime_profile_id="9f4b3d8e-0000-0000-0000-000000000000",
)

computer = client.computers.create(
    name="browser-worker",
    agent_runtime_profile_id="9f4b3d8e-0000-0000-0000-000000000000",
)

Connector secrets are not copied into metadata or returned to the agent. The runtime sees env vars such as REFERO_MCP_TOKEN or ANTHROPIC_API_KEY, but those values are MIOSA egress placeholders (miosa-tok-*). The proxy swaps the placeholder for the provider credential only when the request is allowed.

Default device

Every agent should have a default device policy.

For app builders, sandbox-first should be the default. For browser and RPA agents, computer-first is usually correct.

Tools

Attach only the toolkits the agent needs.

Common bundles:

Accounts and variables

Use account connections and variables instead of chat-pasted secrets.

Never paste a secret into an agent conversation. Store it through the dashboard, API, CLI, or connector flow.

Memory

Memory is durable context the agent can reuse. Keep it scoped.

Good memories:

• brand colors
• project routes
• client preferences
• deployment URLs
• app architecture notes
• recurring task rules

Avoid saving:

• raw secrets
• one-time OTPs
• irrelevant chat history
• stale debugging guesses

Memory should be editable and revocable by workspace owners.

Triggers and jobs

Agents can run manually or automatically.

Triggered agents should write run records, stream events, and respect quotas.

Approval policy

Require approval for risky actions:

• publishing to production
• creating extra child devices above a threshold
• sending messages externally
• writing to connected apps
• spending credits above a configured budget
• deleting files, snapshots, deployments, or data
• using high-privilege credentials

Routine reads, file writes inside the assigned workspace, tests, and preview starts can usually be automatic.

Related