Quickstart & Installation
Here’s the best part about installing NeoSpaxe: you don’t install anything on your laptop, and you don’t have to rewrite your infrastructure.
No background daemon eating your RAM, no proprietary CLI wrapper to keep updated across 14 developer machines, and no web console to log into. NeoSpaxe ships as a self-contained black-box container (ghcr.io/toolboxanonymous/neospaxe-engine:latest) that runs directly inside your CI pipeline.
Step 1: Grab Your License Key
Start your 30-day free trial from the Pricing page. As soon as you finish checkout, Dodo Payments (our merchant of record) emails your license key directly to you.
- No credit card required to start the 30-day trial.
- Includes up to 20 concurrent open preview stacks with all flat fees and hourly fees waived during the trial.
Step 2: Add Your CI Secrets
Open your repository’s CI/CD secret settings (in GitHub, GitLab, or Bitbucket) and make sure these four secrets exist:
| Secret Name | What It Does |
|---|---|
NEOSPAXE_LICENSE_KEY | Your license key emailed by Dodo Payments. Never echoed in logs. |
AWS_ACCESS_KEY_ID | Standard AWS IAM access key for the account where previews should deploy. |
AWS_SECRET_ACCESS_KEY | Standard AWS IAM secret key. Stays strictly inside your CI runner. |
AWS_REGION | Target AWS region for your ephemeral stacks (e.g., us-east-1, ap-southeast-1). |
Nope. The NeoSpaxe engine inspects its own output buffer before printing anything to stdout. If a log line ever contains your NEOSPAXE_LICENSE_KEY or internal operation token, the engine immediately aborts and refuses to print the secret.
Step 3: Add the Deploy & Remove Workflows
Copy the workflow file for your git provider into your repository:
GitHub Actions
Add .github/workflows/github-deploy.yml and github-remove.yml.
GitLab CI/CD
Add the deploy-preview and remove-preview jobs to .gitlab-ci.yml.
Bitbucket Pipelines
Add custom preview pipelines to bitbucket-pipelines.yml.
Step 4: Pick a Stage Name & Run It
Trigger the Deploy workflow and enter a stage name (like pr-42 or feat-billing).
Stage Naming Guardrails
Because NeoSpaxe is designed for ephemeral branch previews—not accidentally overwriting your production database at 4:55 PM on a Friday—the engine enforces strict stage name rules before any cloud provisioning starts:
- Format (
^[a-z][a-z0-9-]{0,39}$):- Must start with a lowercase letter (
a-z). - Can contain lowercase letters, numbers (
0-9), and single hyphens (-). - Maximum 40 characters, cannot end with a hyphen (
-), and cannot contain double hyphens (--).
- Must start with a lowercase letter (
- Protected & Reserved Stage Names:
The engine automatically refuses to deploy or remove any of the following reserved names:
production/prodstaging/stagedevelop/devmain/master
What Happens When You Run Deploy?
When your CI job runs ghcr.io/toolboxanonymous/neospaxe-engine:latest:
- Automatic Workload Detection: NeoSpaxe inspects your workspace. If your repo already includes a native stack config, it uses yours untouched; otherwise, the black-box engine automatically synthesizes a deployment blueprint tailored to your codebase (see Architecture & Auto-Detection).
- Authorization: The container calls the NeoSpaxe ledger API to authorize the stage name against your
NEOSPAXE_LICENSE_KEY. - Provisioning & Heartbeat: It provisions the isolated AWS preview stack inside your CI runner using your AWS credentials, sending a heartbeat every 20 seconds so long builds stay tracked accurately.
- Ledger Summary: Once finished, it prints your stack code and fee summary:
(During your 30-day free trial, both fees print as
stack stk_9f8a7b6c stack fee $20.00 template fee $0.00 hourly $0.20 while this stack stays open$0.00.)
Tearing Down a Preview
When your pull request merges or you’re done testing the branch, run the Remove workflow with the exact same stage_name. The NeoSpaxe engine tears down all AWS resources for that stage and immediately stops the hourly timer for that stack life.