Build applications from source

A site can be a real application. Its source lives under ~/Sites/<name>/, where you or an agent can edit the same files in VS Code. You can ask:

• “Build a Next.js dashboard in TypeScript with an API route.”
• “Create a Python FastAPI service with a health endpoint.”
• “Improve the Flask app already in my Sites folder; keep its framework.”

These projects do not need site.json or Site Editor. If you want visual editing, you can register your real React or JavaScript components, expose typed props, and arrange them in Site Editor with a running app preview. Then site.json stores component metadata and layout while implementations stay in your application. See Edit real application components visually for React and Python/DOM examples. Agents inspect existing source before editing and preserve your language and framework.

Supported deployment profiles

Deployment can add missing profile files such as Dockerfile.vercel and .dockerignore; it preserves existing files. Existing Next.js configuration must enable output: 'standalone' for the generated container build. Python entry points must match the real application module and app object.

Automatic profiles are conveniences. You can keep an Express/plain Node.js application or another Python HTTP framework by supplying your own root Dockerfile.vercel or Containerfile.vercel. Include the runtime, dependency installation, any build steps, and the command that starts your HTTP server on 0.0.0.0 at the platform-configured $PORT. NextOS uploads custom deployment files even when no automatic framework is detected. You do not have to convert the application to Next.js.

Vercel detects these container files and builds the configured HTTP application. See Vercel's Docker deployment guide and container deployment announcement. A source upload still needs a successful build, deployment status, and route checks. This workflow does not establish that a persistent worker or database process can run alongside the HTTP application.

Source to deployment

1. Enable Hosting, connect Google Drive, and allow Drive access in Settings > Privacy > Background runs for the site owner's account. The deployment service reads that account's Drive mirror.
2. Create a site or choose an existing one. Write the source in ~/Sites/<name>/, including dependency manifests and configuration. Source is editable in the VFS; it is not tied to the visual editor.
3. Let the files sync. The browser deployment tool waits for sync and stops on conflicts or failures. A background run sees the Drive copy, so changes that have not synced are not available to that run.
4. Ask the agent to deploy the code project. It submits a production build to Vercel and receives a deployment reference. Builds continue asynchronously; the agent checks status to see when they finish.
5. Check deployment and public-domain status. Once production is ready, NextOS connects <name>.sites.jonkum.in and your verified custom domain to the application. Open the confirmed public URL and check the important user flow. A READY deployment is evidence that the build finished; domain setup and every route, login, or database operation still need their own checks. Ask the agent to report what it actually checked and any remaining setup.

Your application's addresses

Your application keeps the same <name>.sites.jonkum.in address as its site. Each application has its own deployment project; NextOS attaches that exact subdomain after a production build is ready. The deployment's immutable build URL remains available for identifying a specific release. Agents report the ready public address from setup.publicDomains.primaryUrl and keep the build address in deployment.url.

Use Settings > Sites > Domain to buy a domain or attach one you own. The same Domains workflow connects it to the active application and shows the provider's required DNS records. The built-in Sites subdomain remains available. Domain ownership verification and DNS must finish before a custom domain is reported as live.

Links to /s/<name>/ redirect to the ready public application address, preserving the path and query. Your assets, API calls, cookies, and authentication then use the application's own origin.

A pending or failed deployment keeps the last live application route. Deployment and domain reconciliation continue in the background, so the editor does not need to stay open. A first deployment with pending domain setup is not yet live at the requested public address; its status explains the remaining step.

When changing a custom domain, check the application's canonical origin, allowed hosts, and authentication callback URLs. Framework configuration or a database binding may need an update and redeployment before all application behavior uses the new domain.

The agent tools

sites_capabilities explains the available workflows. The scoped source tools take a site slug and project-relative paths, such as main.py:

• sites_source_list inspects the tree; sites_source_read returns a file's content and revision.
• sites_source_write creates a file. Overwriting an existing file requires the expectedRevision returned by a read.
• sites_source_edit replaces one exact oldText with newText, using expectedRevision so a concurrent edit cannot be silently overwritten. On a conflict, the agent reads the file again before editing.
• sites_code_project_deploy submits source; sites_code_project_status returns deployment progress, setup information, and public-domain readiness for the built-in subdomain and custom domain.

An agent uses sites_publish for plain static HTML/CSS/browser JavaScript or section sites. That tool does not install dependencies, build Next.js, or run Python. Section tools such as sites_spec_patch and sites_review apply to site.json, rather than arbitrary application source.

Data and configuration

Applications built in NextOS use the Database app for durable records. For a source application, open Database > Website databases, choose its website, and select Set up website database. NextOS creates a separate MySQL database and restricted login for that website, keeps its credentials in the account vault, and connects the application at deployment. An agent can do the same with sites_code_project_provision_mysql; it needs only the site slug, never a database password.

WordPress provisions a database automatically when no existing database is bound. Other source apps also receive a managed database when platform provisioning is available. Automatic Vercel setup gives each website a dedicated Database service and private persistent storage; its first build may require a retry after the saved build finishes. Existing website database bindings are preserved so a deployment cannot replace production data with an empty database.

WordPress installs its own schema into this MySQL database. Its posts, options, users, and plugin tables appear as live tables in Database once created. In Vercel mode the generated WordPress database drop-in carries SQL over HTTPS. Keep that drop-in in the source; existing custom integrations are preserved and may need adaptation. JavaScript projects receive a server-side Database SQL client. Ordinary native MySQL/ORM drivers, including stock Laravel and Django, require the platform's native MySQL backend. SQL transactions must finish in a single service batch; plugins that depend on native connections or transactions across requests need that native backend. Database discovers tables while open; Refresh databases also refreshes the schema. Changes made by WordPress and Database use the same backing database. Use WordPress for installation and plugin lifecycle operations; Database does not emulate WordPress or replace its SQL schema.

Automatic provisioning needs the platform's connected hosting team and storage permissions, or an operator-configured first-party Database service. If either is unavailable, setup reports that requirement rather than claiming a database exists. See the repository's managed MySQL operator guide.

Keep credentials in managed connections and deployment environment variables. Do not place passwords, private keys, or connection strings in source files. Deployment containers have temporary filesystems: use external storage for records and uploads that must survive a restart.

After a first code deployment returns its project URL, an agent can bind an explicitly chosen, account-owned MySQL connection through sites_code_project_bind_mysql. It references the connection ID and does not need to copy the secret into the conversation. The tool explains which framework-specific settings and application domain configuration are needed. Redeploy after changing a binding. Database schema migrations and application behavior still need their own checks.