# NEXUS AI: full agent documentation > Every document from https://agents.nexusai.run/ in one file. The index is at https://agents.nexusai.run/llms.txt. --- Source: https://agents.nexusai.run/docs/index.md # NEXUS AI Agent Interface NEXUS AI is an agent-native application deployment and infrastructure platform. This site is the machine-readable index for the public NEXUS AI product and API documentation. ## Discovery - [LLM instructions](/llms.txt) - [All docs in one file](/llms-full.txt) - [Capabilities](/capabilities.json) - [OpenAPI](/openapi.json) - [MCP endpoint information](/mcp) - [MCP tool catalog](/mcp/tools.json) - [MCP server card](/.well-known/mcp.json) - [API catalog](/.well-known/api-catalog) ## Product surfaces - Deploy and inspect applications. - Read deployment logs and manage deployment lifecycle actions. - Manage databases, backups, storage volumes, buckets, secrets, and environment configuration through authenticated NEXUS interfaces. - Run background worker services as part of supported full-stack deployments. - Route model traffic through the NEXUS AI Gateway. New here? Start with the [Quick start](/docs/quickstart.md). Operational requests require existing NEXUS authentication and authorization. This site does not grant access to deployments or data. ## Documentation - [Quick start for agents](/docs/quickstart.md) - [Authentication](/docs/auth.md) - [Access tokens](/docs/tokens.md) - [Accounts and 2FA](/docs/account.md) - [Plans and limits](/docs/plans.md) - [Billing](/docs/billing.md) - [AI Builder](/docs/builder.md) - [Deployment](/docs/deployment.md) - [Environments](/docs/environments.md) - [CLI](/docs/cli.md) - [API](/docs/api.md) - [Errors and rate limits](/docs/errors.md) - [MCP](/docs/mcp.md) - [Projects](/docs/projects.md) - [Providers](/docs/providers.md) - [Custom domains](/docs/domains.md) - [Databases](/docs/databases.md) - [Database intelligence](/docs/db-intelligence.md) - [Managed databases](/docs/managed-databases.md) - [SQL safety rules](/docs/sql-safety.md) - [Backups](/docs/backups.md) - [Storage](/docs/storage.md) - [Workers](/docs/workers.md) - [Observability](/docs/observability.md) - [Usage and audit logs](/docs/usage-audit.md) - [GitHub integration](/docs/github.md) - [Organizations](/docs/organization.md) - [Notifications](/docs/notifications.md) - [Support](/docs/support.md) - [Security](/docs/security.md) - [AI providers](/docs/ai-providers.md) - [AI Gateway](/docs/ai-gateway.md) --- Source: https://agents.nexusai.run/docs/quickstart.md # NEXUS AI Quick Start for Agents This page gets an AI agent from zero to a working NEXUS AI connection. Pick MCP for conversational agents, or the REST API for scripts and CI. ## Option 1: MCP (recommended for agents) The MCP server is at `https://mcp.nexusai.run/mcp` (streamable HTTP). It exposes 74 tools. Claude Code: ```bash claude mcp add --transport http nexus-ai https://mcp.nexusai.run/mcp ``` Claude Desktop, in `claude_desktop_config.json`: ```json { "mcpServers": { "nexus-ai": { "type": "http", "url": "https://mcp.nexusai.run/mcp" } } } ``` Cursor: Settings, MCP, Add server, with the same URL. ChatGPT and other clients that support remote MCP servers use the same URL. Sign-in uses OAuth 2.0 with PKCE and dynamic client registration. The client opens a browser on first connect and the user approves the requested scopes. Headless clients run the same flow once and send the access token as `Authorization: Bearer `. Personal access tokens (`nxk_...`) are for the REST API, not for MCP. ## Option 2: REST API 1. Create an access token in the dashboard at https://nexusai.run/settings/tokens, or with `nexus token create`. See [Access tokens](/docs/tokens.md). 2. Call the API with `Authorization: Bearer nxk_...`. ```bash curl -H "Authorization: Bearer $NEXUSAI_TOKEN" https://mcp.nexusai.run/api/gpt/deployments ``` The schemas are in [OpenAPI](/openapi.json). ## First tasks - Confirm identity: `nexusai_whoami`. - List what exists: `nexusai_projects_list`, `nexusai_deploy_list`, `nexusai_managed_db_list`. - Deploy a repository: `nexusai_deploy_source` with `repoUrl`, then poll `nexusai_deploy_status`. - Read logs when something fails: `nexusai_deploy_logs`. ## Rules for agents - Ask the user before any tool marked `destructive` in the [tool catalog](/mcp/tools.json). - Request the narrowest scopes the task needs. - Never paste secrets, tokens, or connection strings into chat, code, or logs. ## Related resources - [Authentication](/docs/auth.md) - [MCP](/docs/mcp.md) - [Plans and limits](/docs/plans.md) - [Errors and rate limits](/docs/errors.md) --- Source: https://agents.nexusai.run/docs/auth.md # NEXUS AI Authentication NEXUS AI has separate authentication surfaces for the platform REST API, personal access tokens, and MCP. ## MCP authentication The MCP service uses OAuth 2.0 with PKCE and dynamic client registration. Interactive MCP clients authenticate in a browser. Headless clients send an OAuth access token as `Authorization: Bearer `. ## REST authentication The REST API supports NEXUS authentication and scoped access tokens (`nxk_`). See [Access tokens](/docs/tokens.md). Access tokens do not work for MCP; MCP uses OAuth. Tokens are independently revocable and should be issued with the narrowest scopes needed for an agent workflow. ## Scope examples - `deployments:read`, `deployments:logs`, `deployments:create`, `deployments:delete` - `secrets:read`, `secrets:manage`, `secrets:delete` - `domains:read`, `domains:manage`, `domains:delete` - `db:read`, `db:query`, `db:admin`, `db:source:delete` - `volumes:read`, `volumes:manage`, `volumes:delete` - `buckets:read`, `buckets:manage`, `buckets:delete` - `managed_db:read`, `managed_db:manage`, `managed_db:delete` - `support:read`, `support:write` `nexusai_whoami` requires authentication but no additional MCP scope. Destructive tools require separate delete or admin scopes and explicit confirmation in the calling agent workflow. ## Related resources - [Security](/docs/security.md) - [MCP](/docs/mcp.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/tokens.md # NEXUS AI Access Tokens Access tokens authenticate REST API and CLI calls from scripts, CI, and agents that do not use MCP. ## Format Tokens start with `nxk_` and are sent as `Authorization: Bearer nxk_...`. The full value is returned once, when the token is created. Store it in a secret manager. ## Create Dashboard: https://nexusai.run/settings/tokens. CLI: ```bash nexus token create --name ci-deploy --scopes deployments:read,deployments:create --expires 90d ``` API: ```http POST https://api.nexusai.run/api/tokens Content-Type: application/json { "name": "ci-deploy", "scopes": ["deployments:read", "deployments:create"], "expiresAt": "2026-12-31T00:00:00Z" } ``` `name` and `scopes` are required. `expiresAt` is optional; a token without it does not expire. ## List and revoke ```bash nexus token list --show-last-used --unused-since 30 nexus token revoke --yes ``` The API equivalents are `GET /api/tokens` and `POST /api/tokens/{id}/revoke`. A revoked token stops working for all later requests. ## Permissions Creating, listing, and revoking tokens needs the `tokens.manage` organization permission, which Owners and Admins have. ## Scopes Use the narrowest set. The full list, and which MCP tool needs which scope, is in [Authentication](/docs/auth.md) and the [tool catalog](/mcp/tools.json). Tokens issued before 2026-05-18 with only the broad `deployments:*` scopes still satisfy the matching fine-grained checks. ## Related resources - [Authentication](/docs/auth.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/account.md # NEXUS AI Accounts The authenticated platform API supports user profile, password, email verification, and two-factor authentication workflows. ## Account operations Users can read and update their profile, change their password, request password reset, verify an email address, and request a verification email. ## Two-factor authentication The API supports checking 2FA status, setting up and verifying TOTP, setting up email-based 2FA, disabling 2FA, regenerating backup codes, and testing a TOTP code. ## Safety Account recovery, password, 2FA, and backup-code operations are security-sensitive. Agents should not request or store passwords, TOTP secrets, or backup codes in prompts, logs, source code, or tickets. ## Related resources - [Authentication](/docs/auth.md) - [Security](/docs/security.md) - [Organizations](/docs/organization.md) --- Source: https://agents.nexusai.run/docs/plans.md # NEXUS AI Plans and Limits Limits an agent should check before it plans work. Current prices and the full comparison are at https://nexusai.run/pricing. ## Plans | Plan | Price | Active deployments | AI requests per day | Team | |---|---|---|---|---| | Free | $0 | 1 | 5 | Solo | | Starter | $29 per month | 2 | 10 | Up to 3 | | Pro | $149 per month | 5 (up to 10 concurrent containers) | 30 | Up to 10 | | Enterprise | Custom | Unlimited | Custom | Unlimited | Healthcare plans: Healthcare Starter ($49 per month, a sandbox not intended for production PHI) and Healthcare Pro ($299 per month). See https://nexusai.run/pricing/healthcare. ## What each plan includes - **Free:** NEXUS AI managed infrastructure only, 3 secrets, public HTTPS endpoint, community support. No AWS, Google Cloud, or Azure targets, no versioned rollbacks, no custom domains. For testing and evaluation, not production business applications. - **Starter:** custom domain, Google Cloud Run target, email support and support tickets, standalone managed databases. - **Pro:** AWS, Google Cloud, and Azure targets, versioned deployments and one-click rollback, AES-256-GCM secrets vault, RBAC, phone support. - **Enterprise:** customer-owned cloud accounts, private build and runtime isolation, SSO (SAML and OIDC), IP allowlisting, advanced audit logs, dedicated support and SLA. Enterprise On-Prem adds self-hosted and air-gapped deployment. ## How limits show up A request past a plan limit fails with a clear error (for example `QUOTA_EXCEEDED` or `PROVIDER_NOT_ALLOWED` on the GPT API). Do not retry these; tell the user which limit was hit. See [Errors and rate limits](/docs/errors.md). ## Related resources - [Billing](/docs/billing.md) - [Providers](/docs/providers.md) --- Source: https://agents.nexusai.run/docs/billing.md # NEXUS AI Billing Billing is an authenticated organization-level platform feature separate from deployment operations. ## Operations Authorized organization users can inspect subscription status, start a trial where eligible, create a checkout or customer-portal session, change or cancel a subscription, and list or retrieve invoices. Healthcare checkout uses a separate route. Billing routes require NEXUS authentication and the appropriate organization billing permission. Payment-provider webhooks are handled by the platform and are not an agent-facing endpoint. ## Safety Subscription changes, checkout, and cancellation have financial consequences. Require explicit authorization and do not place payment details or billing tokens in agent prompts or logs. ## Related resources - [Organizations](/docs/organization.md) - [Authentication](/docs/auth.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/builder.md # NEXUS AI App Builder The NEXUS AI App Builder provides an authenticated, chat-driven development workflow with live preview and deployment handoff. ## Capabilities The Builder API supports sessions, messages, streaming messages, file snapshots, revert/checkpoints, model and provider selection, sandbox synchronization, share/remix links, and GitHub import or push. The MCP server exposes `nexusai_builder_push` and `nexusai_builder_pull` so an agent can send a generated file set to a Builder session and read back the latest files after edits. ## Supported workflows - Generate or import an application into a live preview. - Push complete file snapshots from an agent. - Pull the current Builder files after a user edits the preview. - Revert a session to an earlier checkpoint. - Push a completed project to a new or existing GitHub repository. - Hand the project to the deployment pipeline. ## Safety Builder sessions and source files may contain credentials or private code. Use scoped access, do not include secrets in files, and review a generated diff before deployment. ## Related resources - [Projects](/docs/projects.md) - [Deployment](/docs/deployment.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/deployment.md # NEXUS AI Deployments NEXUS AI accepts container, repository, and source deployments through its authenticated API, CLI, MCP server, and dashboard. ## Source deployment The NEXUS CLI supports source deployment from a GitHub repository: ```bash nexus deploy source --repo --name ``` The service must listen on the `PORT` environment variable. NEXUS health checks can target an HTTP path such as `/health`. ## Deployment lifecycle The authenticated API exposes operations to: - list deployments; - get deployment status; - read deployment logs; - redeploy, start, or stop a deployment; - scale a deployment; - roll back a deployment; and - delete a deployment. These operations are permission- and token-scoped. Destructive actions must not be performed without explicit authorization. ## Providers and services Source deployments can include PostgreSQL, MySQL, Redis, MongoDB, and worker services. The managed Container platform supports full-stack deployments. Cloud Run, AWS App Runner, and Azure Container Apps are supported for single-container deployments where configured. Deployment configuration also supports health checks, environment variables, auto-destroy schedules, provider and region selection, build and start commands, and framework or Dockerfile overrides. Framework detection covers FastAPI, Flask, Django, Express, Next.js, Rails, Laravel, Symfony, PHP, Ruby, Go, Java, and arbitrary container images where the deployment configuration is supported. ## API routes The GPT-compatible API is hosted at `https://mcp.nexusai.run/api/gpt` and requires a NEXUS access token. See [API](/docs/api.md) and [OpenAPI](/openapi.json). ## Related resources - [CLI](/docs/cli.md) - [API](/docs/api.md) - [MCP](/docs/mcp.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/environments.md # NEXUS AI Environments Deployments and secrets carry an environment label so development, staging, and production stay separate. ## Deployment environments Every deployment has one of `DEVELOPMENT`, `STAGING`, or `PRODUCTION`. The CLI defaults to `DEVELOPMENT`: ```bash nexus deploy source --repo https://github.com/you/app --name my-app --environment PRODUCTION ``` The API field is `environment` on `POST /deploy`, `POST /deploy/source`, and the platform deployment routes. ## Keep environments isolated Deploy each environment of the same repository into its own project (`--project `, or `projectId` in the API). Deployments of the same source in the same project can overwrite each other. ## Secrets per environment Secrets are stored per environment name, for example `PRODUCTION`. A project's `vaultEnvironment` decides which environment's secrets its deployments receive. ```bash nexus secret create --name DATABASE_URL --environment PRODUCTION nexus secret list --environment PRODUCTION ``` Secret values are injected when a container starts, so redeploy after changing one. ## Related resources - [Deployment](/docs/deployment.md) - [Projects](/docs/projects.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/cli.md # NEXUS AI CLI The `nexus` CLI runs NEXUS AI operations from a terminal or CI system. Install it with `npm install -g nexusapp-cli@latest` (Node.js 18 or later). Run `nexus --help` for the exact syntax of the installed version. ## Authentication ```bash nexus auth login # browser OAuth nexus auth login --token nxk_... # existing access token nexus auth whoami nexus auth logout ``` In CI, set `NEXUSAI_TOKEN` instead of logging in. `NEXUSAI_URL` overrides the API URL. ## Deployments ```bash nexus deploy source --repo https://github.com/you/app --name my-app --provider docker --services postgres,redis --wait nexus deploy create --image nginx:latest --port 80 --name web --provider gcp_cloud_run nexus deploy list --status RUNNING nexus deploy status my-app --watch nexus deploy logs my-app --follow nexus deploy redeploy my-app --yes nexus deploy rollback my-app --yes nexus deploy scale my-app 3 nexus deploy stop my-app nexus deploy start my-app nexus deploy auto-destroy my-app --in 4h nexus deploy delete my-app --yes ``` Providers: `docker` (NEXUS AI managed, full stack), `gcp_cloud_run`, `aws_ecs_fargate` (AWS App Runner), `azure_container_apps`. Useful `deploy source` options: `--project`, `--environment`, `--branch`, `--env KEY=VALUE`, `--env-file`, `--dockerfile`, `--services`, `--create-db`, `--managed-db `, `--worker-command`, `--auto-destroy `. Run commands in and copy files to a `docker` deployment (these take the deployment ID, not the name): ```bash nexus exec ls -la /app nexus cp ./index.html :/app/public/index.html ``` ## Managed databases ```bash nexus managed-db create shop --local --engine postgres nexus managed-db create prod-db --provider GCP_CLOUD_SQL --engine postgres --engine-version 17 nexus managed-db connection shop --url-only nexus managed-db attach shop --deployment my-app nexus managed-db snapshot shop --notes "before migration" nexus managed-db restore shop --snapshot --new-name shop-restored nexus managed-db query shop "SELECT id, email FROM users LIMIT 10" ``` Always quote SQL. One statement per call; `CREATE DATABASE`, `GRANT`, and similar statements are blocked. See [SQL safety rules](/docs/sql-safety.md). ## Deployment database backups ```bash nexus db services my-app nexus db backup nexus db backups nexus db restore --yes nexus db backup-download --out ./backup.dump nexus db backup-schedule --enable --retention 14 ``` ## Storage ```bash nexus bucket create user-uploads nexus bucket attach nexus bucket upload ./logo.png --key images/logo.png nexus bucket download images/logo.png --share --ttl 300 nexus volume create app-data nexus volume attach --mount /data ``` Redeploy after attaching a bucket, volume, or database. ## Secrets, domains, projects, team, tokens ```bash nexus secret create --name API_KEY --environment PRODUCTION nexus domain add my-app app.example.com nexus domain verify my-app nexus project create --name my-project nexus member invite dev@example.com --role MEMBER nexus token create --name ci --scopes deployments:read,deployments:create --expires 90d ``` ## Output Most read commands accept `--json`. Destructive commands prompt unless `--yes` is passed. Agents should use `--json` and only pass `--yes` after the user approves. ## Related resources - [Deployment](/docs/deployment.md) - [Managed databases](/docs/managed-databases.md) - [Access tokens](/docs/tokens.md) - [Environments](/docs/environments.md) --- Source: https://agents.nexusai.run/docs/api.md # NEXUS AI API NEXUS AI exposes authenticated HTTP APIs for deployments and infrastructure. Public API metadata is available at [OpenAPI](/openapi.json). ## GPT-compatible API The public GPT-compatible API base URL is: ```text https://mcp.nexusai.run/api/gpt ``` The implemented routes include: - `GET /providers` - `GET /deployments` - `POST /deploy` - `POST /uploads/zip` - `POST /deploy/source` - `GET /deployments/{id}` - `GET /deployments/{id}/logs` - `DELETE /deployments/{id}` All GPT-compatible API routes require a Bearer access token. Mutating and destructive operations require the corresponding access-token scope. Rate limits are enforced by the NEXUS API. ## Platform API The main NEXUS API also exposes authenticated routes for: - projects and project members; - AI Builder sessions, files, sharing, sandbox, model, and GitHub integration; - deployments, logs, health, container metrics, scaling, start/stop, redeploy, rollback, and custom domains; - external database sources and database intelligence; - deployment database services, backups, restores, and schedules; - persistent volumes and S3-compatible buckets; - managed databases and snapshots; - secrets, usage, audit, support tickets, GitHub bindings, AI providers, organization settings, and access tokens. The verified route catalog is included in [OpenAPI](/openapi.json). These routes are not proxied by this documentation service; use the NEXUS API origin and its authentication requirements. ## Safety Do not assume a caller is trusted because it identifies as an AI agent. Validate the token, scope, resource ownership, and user authorization before every operational request. ## Related resources - [OpenAPI](/openapi.json) - [MCP](/docs/mcp.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/errors.md # NEXUS AI Errors and Rate Limits How NEXUS AI reports failures, and when an agent should retry. ## Error shapes GPT-compatible API (`https://mcp.nexusai.run/api/gpt`): ```json { "error": "Deployment not found", "code": "DEPLOYMENT_NOT_FOUND", "details": {} } ``` Platform API (`https://api.nexusai.run/api`): ```json { "status": "error", "message": "Query blocked: Statement type not permitted" } ``` MCP tools return the message as tool output with `isError` set. ## GPT API error codes | Code | Meaning | Retry? | |---|---|---| | `INVALID_TOKEN` | Token missing, malformed, or revoked | No. Fix the token | | `TOKEN_EXPIRED` | Token past `expiresAt` | No. Issue a new token | | `INSUFFICIENT_SCOPE` | Token lacks the required scope | No. Ask for a token with the scope | | `RATE_LIMIT_EXCEEDED` | Too many requests | Yes, after `Retry-After` | | `DEPLOYMENT_NOT_FOUND` | Unknown ID, or not in your organization | No | | `PROJECT_NOT_FOUND` | Unknown project ID | No | | `INVALID_REQUEST` | Body failed validation | No. Fix the request | | `DEPLOYMENT_FAILED` | Build or start failed | After fixing the cause. Read the logs | | `DUPLICATE_REQUEST` | Same `requestId` already used | No. The first request is in progress | | `QUOTA_EXCEEDED` | Plan limit reached | No. See [Plans and limits](/docs/plans.md) | | `PROVIDER_NOT_ALLOWED` | Provider not available on the plan | No | | `INTERNAL_ERROR` | Server error | Yes, with backoff | ## HTTP status codes - `400`: invalid request, or blocked by a safety check such as the [SQL rules](/docs/sql-safety.md). - `401`: missing or invalid token. - `403`: the token or user lacks the scope or permission. - `404`: not found, or belongs to another organization. - `429`: rate limited. - `5xx`: server error. Retry with exponential backoff. ## Rate limits | Surface | Limit | |---|---| | GPT API deploy and delete | 20 per hour per organization | | GPT API reads (status, logs, lists) | 60 per minute per organization | | MCP | 300 requests per 5 minutes per token | | Platform API | 100 requests per 15 minutes per client | | Deployment creation | 10 per 15 minutes per user | | Custom domain verification | 3 per 5 minutes per user | GPT API responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`, and a `429` includes `Retry-After` in seconds. ## Idempotency `POST /deploy` and `POST /deploy/source` accept a `requestId`. Reusing it returns `DUPLICATE_REQUEST` instead of starting a second deployment, so it is safe to retry after a network error. ## Related resources - [API](/docs/api.md) - [OpenAPI](/openapi.json) --- Source: https://agents.nexusai.run/docs/mcp.md # NEXUS AI MCP NEXUS AI has an existing MCP service with 74 operational tools. This agent site does not implement a second MCP server. ## Endpoint ```text https://mcp.nexusai.run/mcp ``` Connect clients directly to that URL. The discovery route [`/mcp`](/mcp) on this site returns endpoint metadata, and MCP requests sent to it are redirected (HTTP 308) to the endpoint above; this site does not proxy MCP traffic. The server card is at [`/.well-known/mcp.json`](/.well-known/mcp.json). The public [MCP tool catalog](/mcp/tools.json) lists the verified tool names, required scopes, risk classification, and safety policy without exposing operational data. ## Authentication The MCP service uses OAuth 2.0 with PKCE and dynamic client registration. Interactive clients sign in through a browser; headless clients run the same flow once and send the access token as a Bearer token. Personal access tokens (`nxk_`) are for the REST API, not MCP. OAuth metadata: `https://mcp.nexusai.run/.well-known/oauth-protected-resource` and `https://mcp.nexusai.run/.well-known/oauth-authorization-server`. Setup steps for each client are in the [Quick start](/docs/quickstart.md). ## Tool policy Available tools are determined by the deployed MCP server and the caller's permissions. Do not infer tool availability from a tool name alone, and do not grant destructive permissions by default. The current tool families are identity and discovery, AI Builder, deployments, secrets, custom domains, external database intelligence, deployment databases and backups, persistent volumes, S3-compatible buckets, managed databases, and support tickets. ## Related resources - [API](/docs/api.md) - [Security](/docs/security.md) - [NEXUS MCP endpoint](https://mcp.nexusai.run/mcp) --- Source: https://agents.nexusai.run/docs/projects.md # NEXUS AI Projects Projects group deployments, environments, permissions, and Builder sessions for a tenant. ## Operations The authenticated platform API supports creating, listing, reading, updating, and deleting projects. Project members can be listed, added, updated, or removed according to project permissions. The MCP server exposes `nexusai_projects_list` for project discovery. The tool requires `deployments:read`. ## Environments and permissions Deployments can target development, staging, or production environments. Project and organization RBAC controls which users and tokens may read, create, manage, or delete resources in each environment. ## Related resources - [Security and permissions](/docs/security.md) - [AI Builder](/docs/builder.md) - [Deployment](/docs/deployment.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/providers.md # NEXUS AI Providers NEXUS AI supports multiple deployment providers. The providers available to an organization depend on its plan and configuration. ## Deployment providers - `docker`: NEXUS-managed Container platform for full-stack deployments. - `gcp_cloud_run`: single-container Google Cloud Run deployments. - `aws_ecs_fargate`: single-container AWS App Runner deployment flow. - `azure_container_apps`: single-container Azure Container Apps deployments. Full-stack services such as databases, workers, storage, and backups run on the NEXUS-managed Container platform. Cloud-provider targets are for single-container applications. Enterprise deployments can be configured for customer-owned AWS, Google Cloud, Azure, or on-premises infrastructure where enabled. ## AI providers The authenticated platform also supports organization-configured AI providers. The Builder can select a configured provider, and the AI Gateway can route traffic across Anthropic, OpenAI, Google Gemini, xAI Grok, OpenRouter, and OpenAI-compatible endpoints where configured. ## Discovery Use `nexusai_providers_list` to list deployment providers allowed for the tenant. The REST API also exposes organization AI-provider and deployment-provider configuration routes. ## Related resources - [Deployment](/docs/deployment.md) - [AI Gateway](/docs/ai-gateway.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/domains.md # NEXUS AI Custom Domains NEXUS AI supports attaching custom domains to deployments. ## Operations Authenticated interfaces support listing domains for a deployment, adding a domain, triggering DNS verification, and removing a domain. Adding a domain returns the DNS records required for verification. The MCP tools are: - `nexusai_domains_list` (`domains:read`) - `nexusai_domains_add` (`domains:manage`) - `nexusai_domains_verify` (`domains:manage`) - `nexusai_domains_remove` (`domains:delete`) Verified domains receive TLS certificates through the platform ingress when DNS verification succeeds. ## Safety Verify the target deployment and DNS record before changing a production domain. Removing a domain is a destructive configuration change and requires explicit authorization. ## Related resources - [Deployment](/docs/deployment.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/databases.md # NEXUS AI Databases NEXUS AI supports database services attached to deployments and separately managed databases. ## Supported database surfaces The platform code and public product documentation include PostgreSQL, MySQL, MongoDB, and Redis deployment services. Managed cloud database support includes PostgreSQL and MySQL providers where configured for the organization. ## Operations Authenticated interfaces support database inspection, connection information, service lifecycle operations, schema browsing, query execution, and database backups. The caller must have the required organization or project permission. ## Managed database routes The main API exposes authenticated managed-database routes for listing, inspection, creation, connection details, attachment, detachment, snapshots, restore, and query operations. See [OpenAPI](/openapi.json) for the public GPT-compatible deployment API; managed-database routes remain on the main NEXUS API. ## Safety Treat query execution, credential rotation, restore, and deletion as high-impact operations. Prefer read-only access and create a backup before destructive schema or data changes whenever possible. ## Related resources - [Backups](/docs/backups.md) - [API](/docs/api.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/db-intelligence.md # NEXUS AI Database Intelligence The database intelligence layer connects external PostgreSQL or MySQL sources that are separate from databases provisioned with a deployment. ## Capabilities - Connect, test, list, and remove external database sources. - Inspect a normalized schema graph of tables, columns, types, constraints, and indexes. - Preview queries with an execution plan and safety analysis. - Execute confirmed queries with sandboxing, statement timeouts, and row caps. - Propose a schema fix from deployment log errors. - Apply a reviewed fix proposal with audit logging. ## Safety External database credentials are encrypted at rest. Treat DML and DDL as high-risk. Agents should call query preview first, show the proposed change, and require explicit confirmation before execution. Applying an AI-proposed fix also requires explicit authorization. ## MCP tools The tools are `nexusai_db_source_list`, `nexusai_db_source_connect`, `nexusai_db_source_delete`, `nexusai_db_inspect_schema`, `nexusai_db_query_preview`, `nexusai_db_query_execute`, `nexusai_db_propose_fix`, and `nexusai_db_apply_fix`. ## Related resources - [Databases](/docs/databases.md) - [Backups](/docs/backups.md) - [Security](/docs/security.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/managed-databases.md # NEXUS AI Managed Databases Managed databases are organization resources independent of an application deployment. ## Providers and engines The platform supports local NEXUS-managed databases and managed cloud databases through AWS RDS, Google Cloud SQL, and Azure Database for PostgreSQL or MySQL where the organization is configured for those providers. Redis is also supported for local managed database workflows. ## Operations Authenticated interfaces support listing, inspection, creation, connection details, attachment, detachment, deletion, snapshots, restore, and SQL query operations. A managed database remains independent when an application is redeployed or deleted. ## MCP tools The managed-database tools are `nexusai_managed_db_list`, `nexusai_managed_db_create`, `nexusai_managed_db_delete`, `nexusai_managed_db_connection`, `nexusai_managed_db_attach`, `nexusai_managed_db_detach`, `nexusai_managed_db_snapshot_create`, `nexusai_managed_db_snapshot_list`, `nexusai_managed_db_query`, `nexusai_managed_db_execute`, and `nexusai_managed_db_restore`. ## SQL rules Queries run one statement at a time and some statements, including `CREATE DATABASE`, are blocked. See [SQL safety rules](/docs/sql-safety.md). ## Safety Connection details, credentials, queries, restore, and deletion are sensitive. Use read-only access when possible and verify the target database before any restore or destructive query. ## Related resources - [Databases](/docs/databases.md) - [Backups](/docs/backups.md) - [SQL safety rules](/docs/sql-safety.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/sql-safety.md # NEXUS AI SQL Safety Rules Every SQL statement sent through NEXUS AI (managed database queries and external database intelligence) is checked before it runs. This page lists what passes. ## One statement per request Multiple statements separated by `;` are rejected with `Multi-statement SQL is not allowed`. Semicolons inside quoted strings and dollar-quoted function bodies are fine. ## Allowed | Class | Statements | |---|---| | Read | `SELECT`, `EXPLAIN` | | Write (DML) | `INSERT`, `UPDATE`, `DELETE` | | Schema (DDL) | `CREATE`, `ALTER`, `DROP TABLE`; `CREATE`, `DROP INDEX`; `CREATE`, `DROP VIEW`; `CREATE`, `DROP FUNCTION` and `PROCEDURE`; `CREATE`, `DROP TRIGGER`; `TRUNCATE` | `UPDATE` and `DELETE` must include a `WHERE` clause. ## Blocked These fail with `Query blocked: Statement type not permitted` or `Blocked operation detected`: - `CREATE DATABASE`, `DROP DATABASE` - `GRANT`, `REVOKE`, `CREATE ROLE`, `ALTER ROLE` - `CREATE EXTENSION`, `CREATE SCHEMA` - `COPY ... PROGRAM`, `pg_read_file`, `pg_write_file`, `pg_ls_dir`, `SHUTDOWN` - Anything else not in the allowed table ## Alternatives when a statement is blocked - Need another database: create a new managed database with `nexusai_managed_db_create` or `nexus managed-db create`. - Need unrestricted access: get credentials with `nexusai_managed_db_connection` (audit-logged) and connect with `psql` or `mysql`. Confirm with the user first. ## Permissions - Managed databases: reads need `managed_databases.read` (MCP scope `managed_db:read`); writes and DDL need `managed_databases.manage` (`managed_db:manage`). `nexusai_managed_db_query` is read-only; use `nexusai_managed_db_execute` for writes. - External sources: `nexusai_db_query_preview` runs `EXPLAIN` for reads and shows the plan for writes. DML and DDL through `nexusai_db_query_execute` need `confirmed: true`. Results are capped at 1,000 rows with a 5 second statement timeout by default. - Managed database queries time out after 30 seconds. ## Examples ```bash nexus managed-db query shop "SELECT id, email FROM users LIMIT 10" nexus managed-db query shop "CREATE TABLE notes (id serial PRIMARY KEY, body text NOT NULL)" nexus managed-db query shop "UPDATE notes SET body = 'hi' WHERE id = 1" ``` Always quote the SQL in a shell. ## Related resources - [Managed databases](/docs/managed-databases.md) - [Database intelligence](/docs/db-intelligence.md) --- Source: https://agents.nexusai.run/docs/backups.md # NEXUS AI Backups NEXUS AI supports backup and restore operations for supported database services. ## Capabilities Authenticated backup routes support: - creating a backup; - listing backups; - uploading a backup; - restoring a backup; - restoring a backup into another compatible service; - creating a signed download URL; and - scheduling backup behavior where supported. ## Authentication Backup operations require NEXUS authentication. Backup download URLs are bearer capabilities; treat them as secrets and do not log or publish them. ## Safety Agents should create a backup before potentially destructive database operations whenever possible. Do not delete backups unless explicitly authorized. Verify database engine compatibility and the target service before a restore. ## Related resources - [Databases](/docs/databases.md) - [API](/docs/api.md) - [MCP](/docs/mcp.md) --- Source: https://agents.nexusai.run/docs/storage.md # NEXUS AI Storage NEXUS AI exposes two storage models through its authenticated API: persistent volumes and object-storage buckets. ## Persistent volumes Volume operations include listing, creating, attaching, detaching, and refreshing usage. Volume routes require the appropriate organization permission. ## Object-storage buckets Bucket operations include listing, creating, attaching, detaching, refreshing usage, rotating credentials, listing files, uploading files, creating download URLs, downloading files, and deleting files. Each bucket uses a scoped service account. Bucket attachments inject S3-compatible variables such as `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, and `S3_REGION` on the next deployment. ## Safety Storage credentials, signed URLs, and uploaded data are sensitive. Agents should use the narrowest available permission, avoid logging credentials, and require explicit authorization before deleting volumes, buckets, or files. ## Related resources - [Security](/docs/security.md) - [API](/docs/api.md) - [MCP](/docs/mcp.md) --- Source: https://agents.nexusai.run/docs/workers.md # NEXUS AI Workers NEXUS AI supports background worker services as part of supported full-stack deployments. Worker services are deployed and operated as components of an application stack rather than through a separate public documentation-site endpoint. ## Deployment Worker configuration is supplied with the application deployment definition. Use the same authenticated deployment, inspection, logs, scaling, and rollback controls that apply to the application stack. ## Safety Workers can process queues, modify databases, and call external services. Give worker credentials only the scopes they need, and review scaling or restart operations before applying them to production. ## Related resources - [Deployment](/docs/deployment.md) - [API](/docs/api.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/observability.md # NEXUS AI Observability NEXUS AI exposes deployment logs, health, container metrics, usage statistics, and audit records through authenticated interfaces. ## Deployment signals Agents can inspect deployment status, read build or runtime logs, query health, and read container metrics and metrics history. Health checks can be enabled or disabled and can target an HTTP path. ## Usage The platform provides AI request counts, detailed usage statistics, and usage history. The MCP tool `nexusai_usage_stats` returns organization usage, quotas, and deployment counts. ## Audit Audit logs record platform actions with actor identity, token name where applicable, timestamp, request context, and result. Audit routes include logs, event types, security summaries, security metrics, user activity, and CSV export for authorized organization administrators. ## Safety Logs may contain application data. Do not paste secrets or credentials into logs, and restrict audit and usage access to the minimum required organization permission. ## Related resources - [Deployment](/docs/deployment.md) - [Security](/docs/security.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/usage-audit.md # NEXUS AI Usage and Audit Logs Usage shows what an organization consumes. The audit log records who did what, including actions taken by agents. ## Usage | Route | Returns | |---|---| | `GET /api/usage/stats` | Usage summary for the organization | | `GET /api/usage/history` | Usage over time | | `GET /api/usage/ai-requests` | AI request counts | MCP: `nexusai_usage_stats`. Needs the `usage.read` permission (Owner, Admin, Auditor, Billing Manager). ## Audit log | Route | Returns | |---|---| | `GET /api/audit/logs` | Audit events, filterable | | `GET /api/audit/event-types` | The event types that can appear | | `GET /api/audit/security-summary` | Security event summary | | `GET /api/audit/security-metrics` | Security metrics | | `GET /api/audit/export` | Export of the audit log | | `GET /api/audit/user/{userId}` | Events for one user | Needs the `audit.read` permission (Owner, Admin, Auditor). There is no MCP tool for the audit log. ## What is recorded Platform actions such as deployments, secret changes, managed database connection reads, backups, restores, and configuration changes. Each entry has a timestamp, the actor, and the result. Use `GET /api/audit/event-types` for the exact list. ## Related resources - [Security](/docs/security.md) - [Organizations](/docs/organization.md) --- Source: https://agents.nexusai.run/docs/github.md # NEXUS AI GitHub Integration NEXUS AI supports GitHub repository import, repository bindings, webhook-driven deployments, and deployment triggers for configured organizations. ## Operations The authenticated platform API supports installing the GitHub integration, listing repositories and bindings, creating or updating bindings, deleting bindings, triggering a binding deployment, and inspecting webhook deliveries. The AI Builder can import a GitHub repository and push a Builder project to a new or existing repository. ## Safety Review repository access and deployment binding settings before enabling automatic deployments. Keep repository tokens and webhook signing secrets out of logs and application source. ## Related resources - [AI Builder](/docs/builder.md) - [Deployment](/docs/deployment.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/organization.md # NEXUS AI Organizations Organizations provide tenant isolation, members, roles, provider configuration, notifications, and organization-level permissions. ## Operations Authorized organization administrators can list and invite users, update roles, suspend or activate members, reset a member password, inspect the role catalog, configure deployment settings and provider credentials, and manage notification settings. ## Roles and scopes The platform includes Owner, Admin, and Developer roles. MCP uses narrow OAuth scopes for deployment, secrets, domains, databases, storage, managed databases, and support. REST API routes additionally enforce organization and project RBAC permissions. ## Safety Member suspension, role changes, provider credential changes, and deployment-setting changes affect other users and services. Require explicit authorization and record the intended scope of the change. ## Related resources - [Security](/docs/security.md) - [Authentication](/docs/auth.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/notifications.md # NEXUS AI Notifications Authenticated users can read platform notifications and manage read state. ## Operations The API supports listing notifications, reading the unread count, marking all notifications as read, and marking one notification as read. Organization notification preferences are managed through organization settings. ## Related resources - [Organizations](/docs/organization.md) - [Observability](/docs/observability.md) --- Source: https://agents.nexusai.run/docs/support.md # NEXUS AI Support Authenticated agents can manage organization support tickets through the platform API and MCP. ## Operations Support workflows include creating a ticket, listing tickets, reading a ticket and its message thread, replying, and updating ticket status. The MCP tools are `nexusai_support_ticket_create`, `nexusai_support_ticket_list`, `nexusai_support_ticket_get`, and `nexusai_support_ticket_reply`. Supported ticket categories include general, billing, technical, deployment, and database. Supported priorities include LOW, MEDIUM, HIGH, and URGENT. ## Safety Include tool names, request IDs, and non-sensitive error details when reporting an issue. Do not include access tokens, secret values, database passwords, or signed URLs in a ticket. ## Related resources - [Security](/docs/security.md) - [MCP tools](/mcp/tools.json) --- Source: https://agents.nexusai.run/docs/security.md # NEXUS AI Security NEXUS AI operational interfaces are authenticated and authorization-scoped. This documentation service is public because it contains product and interface metadata; it does not expose deployment data or secrets. ## Authentication The NEXUS MCP service supports OAuth 2.0 with PKCE for interactive clients. The GPT-compatible API supports NEXUS Bearer access tokens. Use the authentication method required by the specific interface. ## Authorization Use least privilege. Separate read permissions from write and destructive permissions. Examples of useful boundaries include: - `deployment.read` - `deployment.logs` - `deployment.create` - `deployment.manage` - `database.read` - `database.write` - `secrets.read` - `secrets.manage` High-risk operations such as deletion, secret writes, database writes, and restore should require explicit authorization and a narrowly scoped credential. ## Tenant controls NEXUS AI isolates organizations, runtime networks, volumes, and object-storage buckets. Organization roles include Owner, Admin, and Developer. Enterprise configurations can use SAML or OIDC SSO and customer-owned cloud deployments where enabled. The platform documents HIPAA-aligned safeguards for regulated environments, including tenant isolation, encrypted secrets and backups, scoped bucket IAM, audit logs, customer-owned cloud deployment, and BAA availability for eligible plans. Customers remain responsible for their application and compliance program. ## Encryption and audit Secrets and bucket credentials use AES-256-GCM encryption at rest. Secrets are injected at container start and are not returned by secret-list operations. Platform actions are recorded in the audit trail for authorized administrators. ## Logging Never log API keys, Bearer tokens, OAuth credentials, database passwords, secret values, or signed download URLs. ## Related resources - [API](/docs/api.md) - [MCP](/docs/mcp.md) - [Backups](/docs/backups.md) --- Source: https://agents.nexusai.run/docs/ai-providers.md # NEXUS AI Providers AI provider configurations are the model credentials an organization brings to NEXUS AI (bring your own key). The AI Builder and other AI features use them. ## Supported providers `ANTHROPIC`, `OPENAI`, `GOOGLE`, `COHERE`, `XAI`, `OPENROUTER`, and `CUSTOM` (any OpenAI-compatible endpoint, set with `baseUrl`). ## Routes | Route | Action | |---|---| | `GET /api/ai-providers` | List configurations (keys are not returned) | | `POST /api/ai-providers` | Add one: `provider`, and `apiKey` or `secretId`, plus optional `model`, `maxTokens`, `temperature`, `baseUrl` | | `PUT /api/ai-providers/{id}` | Update, including `enabled` | | `DELETE /api/ai-providers/{id}` | Remove | All need the `aiProviders.manage` permission (Owner, Admin). Prefer `secretId`, which points at a key already in the secrets vault, over sending `apiKey` directly. Custom `baseUrl` endpoints must resolve to public addresses; private and internal addresses are rejected. ## Managed AI Without a key of your own, the AI Builder uses NEXUS-managed models within the plan's daily AI request allowance. See [Plans and limits](/docs/plans.md). The providers available to the Builder are listed at `GET /api/builder/providers`. ## Related resources - [AI Builder](/docs/builder.md) - [AI Gateway](/docs/ai-gateway.md) - [Security](/docs/security.md) --- Source: https://agents.nexusai.run/docs/ai-gateway.md # NEXUS AI Gateway NEXUS AI provides an AI Gateway for model traffic. The gateway supports OpenAI-compatible and Anthropic-compatible interfaces, provider routing, failover, model aliases, usage tracking, budgets, rate limits, and guardrails where configured. ## Interfaces The documented gateway interfaces include: - OpenAI-compatible requests under `/v1`; - Anthropic-compatible requests under `/v1/messages`; and - an MCP gateway for aggregating configured MCP servers. Configured providers can include Anthropic, OpenAI, Google Gemini, xAI Grok, OpenRouter, and other OpenAI-compatible endpoints where enabled. Provider keys remain in the gateway rather than application source. ## Credentials Provider keys are stored and used by the gateway. Agents should not place provider credentials in application source code or send them to this public documentation service. ## Availability Gateway features, providers, budgets, and routing policies depend on the NEXUS deployment and organization configuration. Inspect the authenticated gateway configuration before relying on a provider or model alias. ## Related resources - [Security](/docs/security.md) - [MCP](/docs/mcp.md) - [NEXUS AI Gateway](https://nexusai.run/ai-gateway)