AWS Marketplace

Operations & Troubleshooting

This runbook covers the customer-operated AWS Marketplace appliance, release 2026-09-16.1. Start with Install on AWS for a new deployment. Your AWS administrator owns infrastructure, access, capacity, backups, and incident response.

Monitor the deployment

Keep both infrastructure and email-feedback SNS subscriptions confirmed and monitored. Investigate alarms; do not mute them as a substitute for resolving the cause.
In ECS, inspect the bb-appliance cluster for desired/running counts, stopped-task reasons, deployment failures, and unhealthy load-balancer targets. Use CloudWatch service logs to correlate failures with a UTC timestamp and task ID.
Check https://api.<your-domain>/healthz for HTTP 200, but also periodically verify login and a representative agent tool task. HTTP health alone does not prove Bedrock, SMTP, or sandbox readiness.
Track Bedrock throttling/access errors, running and suspended MicroVMs, remaining quota headroom, SES sending/reputation, database storage, and backup freshness.
Treat IAM, credentials, network restrictions, domain changes, and optional integrations as reviewed operational changes. Never grant broad vendor access or paste Secrets Manager values into tickets.

Troubleshoot by symptom

Symptom	What to check next
Certificate or DNS validation remains pending	Check the public zone belongs to the deployment account, the parent delegates to its actual name servers, and ACM validation records resolve publicly. Do not bypass TLS warnings.
CloudFormation fails on a resource or image pull	Read the earliest failure in Events. Check Marketplace subscription in this account, us-east-1, SCP/IAM restrictions, service quotas, and CodeBuild/ECS logs. Retrying with a second stack can collide with fixed resource names.
App returns 403 while API health is good	Check the web-app WAF allowlist against your current public IPv4/VPN address. AppAllowedCidrs affects the app host, not every host.
API returns 502/503 or ECS tasks keep restarting	Inspect ALB target health and stopped-task reasons, then logs for the affected service and its database/network dependencies. Do not assume it is a model quota failure.
Error sending magic link email	Check SES region, sender verification, DKIM, production/sandbox status, sending health/limits, suppression, and authentication-service SMTP logs. See Login Email Setup.
Email arrives but login fails	Use the newest link in the browser/profile that requested it; check the app/auth domain and callback. For a routing error, record the token-free path, release, and request ID. Do not share the full URL or edit authentication tokens.
Signup disabled or user not found	Use the provisioned FirstUserEmail or ask the administrator to provision/invite the user. Marketplace subscription is not an application account; do not enable open signup to work around this.
Model unavailable / Bedrock 403	Separate model/account enablement from IAM/SCP denial. Verify exact model ID, Mantle endpoint, and account with AWS Support. A parent account approval or Runtime test is not enough.
Bedrock 429 / throttling	Check the applicable Mantle input/output quotas and service capacity, reduce concurrent work, and request needed capacity through AWS. Do not switch endpoints merely to reuse a different quota.
MicroVM allocation fails / ServiceQuotaExceededException	Check applied Lambda MicroVM memory, including suspended VMs. Reserve 8 GiB per Brainbase VM plus headroom. Request capacity or perform owner-approved cleanup through Brainbase.
VM exists but shell or tools fail	Inspect task events, runtime readiness, and MicroVM logs. A RUNNING provider state is not an application-readiness check. Record task/machine IDs and release for support.
Browser, memory, or connector authentication fails	Check that feature is available and configured in this appliance release, then check its credentials and permissions. Diagnose it separately from core model and shell execution.

Use Model Access & Quotas and Login Email Setup for detailed checks. Share redacted errors and timestamps, not secrets, login links, or user content.

Backups and recovery

PostgreSQL uses a dedicated encrypted 200 GiB EBS data volume. The template configures nightly EBS snapshots with seven retained snapshots and nightly logical database dumps to S3. Verify recent snapshots and dumps exist and monitor backup-success alarms; resource creation is not proof a backup ran.

Assign an owner, retention policy, and recovery objectives. Test restoration before relying on backups for production. Restoring a database snapshot needs a compatible volume/instance mapping and coordinated application recovery; contact help@brainbaselabs.com for a release-specific restoration procedure. Database backups alone do not cover all uploaded files, integration state, or unsaved MicroVM-local data. Review S3/workspace retention separately.

Upgrade an existing installation

Record the current template version and parameters, verify recoverable backups, and review the new version notes. Coordinate a maintenance window; do not assume zero downtime.
In CloudFormation, update the existing stack using the published template URL for the selected Marketplace release. Preserve intended domain, zone, contacts, first-user, and network settings unless changing them deliberately.
Review the change set, especially replacements or deletions affecting database/storage resources, IAM, DNS, and email. Stop and investigate unexpected destructive changes before execution.
Execute the reviewed change set and wait for UPDATE_COMPLETE. The release updates image references and applies missing schema migrations through its migration ledger. A failed migration requires diagnosis; changing an image back does not undo a database migration.
Repeat health, login, model, and tool checks. For upgrades introducing email feedback, confirm the new SNS subscription and re-test feedback delivery.

Publication is not automatic rollout

A newly approved Marketplace version does not update your running stack. Customers choose when to apply it. SES approval and quota changes are separate account settings and generally do not require a template update.

Costs and external dependencies

Your Marketplace offer defines Brainbase platform charges, including the appliance-hour and estimated model-token-spend dimensions where applicable. The token-spend dimension is a Brainbase platform charge, not a replacement for AWS's Bedrock bill. AWS separately charges for infrastructure, model usage, sandbox compute/storage, networking, email, and monitoring. Idle application services, NAT, ALB, database, and retained storage still incur charges. Configure AWS budgets and review your actual offer; this guide is not a fixed monthly cost quote.

The database, secrets, application storage, logs, MCP servers, and model calls run using your account's AWS resources. This is not a promise that every optional feature stays inside your account. Review the selected release's Marketplace usage instructions and your data policy before enabling integrations.

Dependency	When data leaves the account
Installation downloads	The installer retrieves tooling from github.com and release images from the AWS Marketplace registry.
Brainbase-operated services	Optional workflows, the GitHub connector, and connector agent streaming use Brainbase-operated endpoints while those features are in use.
Optional third-party integrations	Pipedream, Portkey, Twilio, LiveKit, Deepgram, and Resend remain off until configured with credentials; enabled features send relevant data to those providers under your terms.
Slack	The included connector requires a real Slack app and credentials. A deployed connector is not an installed or authorized Slack integration.
Authentication email	SES in your account delivers email to recipient mail providers. Login links and recipient information necessarily leave your VPC for delivery.

The broader Brainbase documentation also describes hosted SaaS features. Do not assume every listed model, integration, sign-in provider, or managed service is included/configured in your appliance version. Validate the selected release and each intended integration before customer handoff.

Retire VMs or the deployment safely

For individual sandboxes, obtain the owner's approval, export needed local files, and use Brainbase's machine-management path so its records stay consistent. Suspension is not termination and still consumes allocated-memory quota. Never delete another user's suspended VM merely to make a smoke test pass.

For a full retirement, stop new work, preserve required data and backups, inventory runtime-created MicroVMs and other resources, and review the CloudFormation deletion plan with your administrator. The database data volume, snapshots, and shared secrets are retained; populated buckets or other retained resources may also need explicit cleanup. Verify what remains and its costs rather than assuming stack deletion removes everything.

Never delete a configuration set while a sender identity still references it. Check other senders and workloads before changing shared SES settings. Infrastructure deletion and Marketplace cancellation are separate actions: review your agreement's cancellation/renewal terms and confirm both intended outcomes. Retained data deletion is irreversible; obtain explicit approval.

If you reinstall, recheck domain delegation and email readiness. A recreated hosted zone can have different name servers; a recreated sender identity or SNS subscription can need verification or confirmation again. Do not assume the previous installation's DNS or email checks still pass.

Get help

Contact help@brainbaselabs.com, Monday through Friday, 9am-7pm Pacific Time; first response within one business day. There is no infrastructure availability SLA for the customer-operated appliance. Include the release, region, stack status, affected feature, UTC timestamp, redacted error, and task/machine or AWS request ID. Share account details only through the agreed support channel. AWS Support or your AWS account team handles AWS model enablement, quotas, and SES production approval.