Documentation

Everything you need to know to deploy your app on Neul.

Projects & Autopacks

A project is your application on Neul. Each project has one linked repository, one or more environments, and a build history.

When you create a project, you choose an autopack — a preconfigured runtime that handles how your app is built, packaged into a container image, and deployed. Autopacks configure the build command, start command, base image, and port automatically so you don't have to write a Dockerfile.

Available autopacks:

  • Bun — TypeScript and JavaScript projects on the Bun runtime
  • Neulix — React SSR apps built with the Neulix framework
  • Node.js — JavaScript/TypeScript projects on the Node.js runtime
  • Go — Go applications, compiled to a static binary
  • Python — Python applications with pip dependency management
  • Rust — Rust applications, compiled with Cargo
  • Django — Python web framework for rapid development
  • FastAPI — High-performance Python API framework
  • Deno — TypeScript and JavaScript projects on the Deno runtime
  • Next.js — React framework with server-side rendering
  • Bun MCP — MCP (Model Context Protocol) server on Bun
  • Node MCP — MCP (Model Context Protocol) server on Node.js

Each autopack has a template repository. When you create a project, you can choose to bootstrap a new GitHub repository from the template — giving you a ready-to-deploy boilerplate with a health check endpoint already configured.

Each account can have up to 5 projects.

Post-install commands:

Some projects need extra setup after dependencies are installed — for example, generating a Prisma client, installing a Python framework like FastAPI or Django, or tidying Go modules. You can select a post-install command in your project's Settings page. It runs automatically during every build after dependencies are installed.

GitHub Integration

Neul connects to your GitHub account to access your repositories and trigger builds.

Setup:

  1. Go to Settings and click "Connect GitHub"
  2. Authorize Neul on GitHub and install the app on your account or organization
  3. Back in Neul, select which installation to link

Once connected, go to your project's Repository page, search your repos, and link the one you want to deploy. This gives Neul read access to clone and build your code.

The Repository page also shows open pull requests from your linked repo. You can trigger a build directly from any PR branch with one click.

You can have one GitHub connection per account.

Builds

A build takes your source code from GitHub, compiles it, and creates a container image ready for deployment.

To trigger a build:

  1. Go to your project's Builds page and click "New build"
  2. Select a branch — Neul shows all available branches from your repo
  3. Neul clones your repo, installs dependencies, runs the build command, and packages the result into a container image

You can also build directly from a pull request. Go to the Repository page — open PRs are listed with a "Build" button next to each one.

Auto-deploy:

When triggering a build, you can enable "Deploy automatically after build succeeds" and choose a target environment. If the build succeeds, Neul will deploy it to that environment automatically — no extra clicks needed.

Build progress is shown in real-time with full logs. Builds go through statuses: Pending → Building → Succeeded or Failed. If a build fails, the logs show exactly what went wrong.

Once a build succeeds, you can deploy it directly from the build detail page — click "Deploy", choose an environment, and you're live.

Only successful builds can be deployed to environments.

Limits:

  • Up to 3 concurrent builds per account (2 per project)
  • Up to 30 builds per day per account (15 per project)

Instance Slots

Neul uses a prepaid model. An instance slot is a one-time purchase that powers one running environment for a set duration (typically 30 days).

How it works:

  • Purchase a slot from the Instances page — it's a one-time payment, no subscription
  • The slot is active for the duration specified by its tier
  • Link it to an environment when you create one
  • When it expires, purchase a new slot and swap it in — your app stays running during the switch with zero downtime
  • If a slot expires without a replacement, the linked environment is automatically stopped

Instance tiers define the resources your environment gets — CPU, memory, disk type, and duration. Different tiers are available at different price points.

You can move slots between environments at any time. If you delete an environment, its slot becomes available again.

Refunds are available within 10 days of purchase — request one from the Instances page via the three-dot menu on any active slot. Expired slots cannot be refunded.

You can purchase up to 5 instance slots per day.

Each account can hold up to 3 instance slots at a time.

Environments

An environment is where your app runs. Each environment has its own subdomain, secrets, and deployment history.

Types:

  • Production — one per project. Gets the clean subdomain (e.g., myapp.neul.dev).
  • Staging / other — any name you choose. Subdomain format: myapp-staging.neul.dev.

You can also point custom domain hostnames to any environment using the Domains page — for example, map yourdomain.com to production and staging.yourdomain.com to staging.

Creating an environment requires an available instance slot. You assign the slot during creation.

You can view real-time application logs from the environment detail page while your app is running.

Environment statuses: Idle (created, never deployed), Running, Stopped, Deploying, Provisioning (SSL certificate being issued).

Each account can have up to 2 environments.

Deployments

A deployment takes a successful build and runs it in an environment. You can deploy any successful build to any environment in the same project.

Ways to deploy:

  • From the Environments page — click the three-dot menu on an environment and select "Deploy"
  • From a Build detail page — click "Deploy" after a successful build and choose an environment
  • From the Deployments page — click "New deployment" and select both a build and an environment

During deployment, you can watch each step:

  1. Pulling — downloading the container image
  2. Booting — starting the container
  3. Health check — verifying your app responds to HTTP. Neul checks /health first, then falls back to / — so your app just needs to return a 2xx or 3xx on either path.
  4. Switching — routing traffic to the new container
  5. Live — deployment complete, app is serving traffic

Redeployments are zero-downtime: the new container boots and passes a health check before traffic is switched. If the new container fails, the old one keeps running — your app stays up.

You can redeploy the current build (restart) or deploy a different build at any time.

Limits:

  • Up to 30 deploys per day per account (15 per project)

Environment Variables

Environment variables let you store secrets and configuration per environment. Values are encrypted and stored securely — they're never exposed in the UI after being set.

Usage:

  • Go to an environment's detail page
  • Add variables with uppercase keys (e.g., DATABASE_URL)
  • Variables are injected into the container on the next deploy
  • You can update or remove variables at any time
  • Use "Import .env" to bulk-import from a .env file, or "Clear all" to remove everything at once

Changing a variable doesn't automatically restart your environment. Redeploy to pick up the new values.

Each environment can have up to 50 variables.

Custom Domains

Every environment gets a free *.neul.dev subdomain with automatic HTTPS. You can also bring your own domain.

Domains are managed from the Domains page in the console. One domain can serve multiple projects — for example, your main site on the apex and an API on a subdomain.

Step 1: Verify ownership

  1. Go to the Domains page and click "Add domain"
  2. Enter your apex domain (e.g., myapp.com)
  3. Add a TXT record at your DNS provider with the verification token shown (e.g., neul-verify=abc123) on your apex domain (host: @)
  4. Click "Verify" — Neul checks the TXT record to confirm you own the domain

You have 48 hours to complete verification after adding a domain. Unverified domains are automatically removed after this window — you can always re-add the domain and try again.

Step 2: Create mappings

After verifying, create mappings to route subdomains to your environments. Each mapping connects a hostname to an environment — across any of your projects. Your apex domain can stay on another service (e.g., Vercel, Netlify) while subdomains route through Neul.

  • For the apex (e.g., myapp.com): add an A record pointing to the IP shown
  • For subdomains (e.g., api.myapp.com): add a CNAME pointing to the target shown

Neul verifies that each hostname resolves to our infrastructure before activating the mapping. HTTPS is provisioned automatically via Let's Encrypt.

You can add, remove, or change mappings at any time. Removing a domain removes all its mappings.

Each domain can have up to 10 mappings.

MCP (AI Assistants)

Neul has an MCP server that lets AI assistants like Claude manage your projects, trigger builds, deploy, and check logs — all through natural language.

Setup with Claude Code:

  1. Add the server to your project's .mcp.json:
    {
  "mcpServers": {
    "neul": {
      "type": "http",
      "url": "https://mcp.neul.io/"
    }
  }
}
  2. Run /mcp in Claude Code and authenticate with your Neul account
  3. Ask Claude to manage your Neul projects

What you can do:

  • Create projects with any autopack
  • Trigger builds and deploy to environments
  • Manage environment variables
  • View build, deployment, and runtime logs
  • Check project status and metrics
  • List and manage instance slots

Example prompts:

  • "Create a new Bun project called my-api"
  • "Build main and deploy to production"
  • "Set DATABASE_URL on staging"
  • "Why did the last build fail?"
  • "Show me the runtime logs for production"

The MCP server uses OAuth for authentication. Your connections are scoped to your account and can be viewed or revoked in Settings under "MCP Connections".

Support

Need help or want to share feedback? We're here for you.