ACE Engine

Local-first AI development server that orchestrates AI coding agents, manages task queues, and serves the DevLay developer overlay — all from your machine.

What is ACE Engine?

ACE Engine is a Rust-powered CLI and background server that:

• Scaffolds full-stack apps — ace init creates a monorepo with NestJS backend, Next.js frontend, and shared types
• Manages AI agents — ships with Cursor support; extensible via the Agent trait for custom agents
• Task queues — queue prompts, track threads, switch between parallel work streams
• DevLay UI — launches an embedded developer overlay (port 6008) for chat, file browsing, logs, and settings
• Works offline — no cloud account required; generates local app IDs and runs entirely on your machine

Prerequisites

Tool	Version	Notes
Rust	1.75+	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Node.js	20+	Required for customer app services and DevLay
pnpm	9+	npm install -g pnpm
Cursor	Latest	Optional — needed if using the Cursor agent

Install

macOS desktop app (recommended)

Download the latest .dmg from Releases, drag ACE Desktop into /Applications, and launch. The DMG bundles the ace CLI alongside the GUI — click "Install command line tool" in the topbar to symlink ace into /usr/local/bin/ so it's available in every terminal.

First launch: macOS may say "ACE Desktop can't be opened" — right-click the app → Open → confirm Open. One-time Gatekeeper quarantine check; the DMG ships with a README – First Launch.txt next to the app with the same instructions.

CLI only (macOS / Linux)

curl -fsSL https://github.com/sarathharmony/ace-engine/releases/latest/download/install.sh | bash

Installs ace to ~/.local/bin/ace. Override with ACE_INSTALL_DIR=/usr/local/bin, or pin a version with ACE_VERSION=v0.8.3.

Updating

ace update             # install the latest release
ace update --check     # just report what's available
ace update --tag v0.8.3 # pin to a specific version

From source

git clone https://github.com/sarathharmony/ace-engine.git
cd ace-engine
cargo install --path . --no-default-features

Publish a parent app

Parent apps are reusable kits that other developers pull down via ace createapp <friendly-name>. The publish flow is:

1. Link your GitHub account to acetoprod.com. The platform verifies that the publisher has push/admin on the repo they claim before accepting a publish — no linked account means a 400. Connect via https://acetoprod.com/settings (or GET /api/github/auth).
2. Scaffold a blank kit: ace createapp --blank my-kit (or ace init my-kit).
3. Flip DevLay into parent-app mode — set parentApp.mode: "build" in ace.json (or toggle the Parent App pill in the DevLay composer). Every prompt you send to the agent is then prefixed with the bundled parent-app rules (see packages/devlay-oss/src/prompts/parent-app-rules.ts).
4. Shape the kit by prompting the agent — services, ace-setup.sh, README, .env.example. The parent-app rules guide the agent on what to add and where.
5. Push to GitHub under an org/user you have push rights on. The repo must be public so other users can ace createapp it.
6. Publish with POST /api/parent-apps (auth: bearer from ace login). The payload shape is {friendlyName, githubRepoUrl, branch, commitSha, tags?, shortReadmeMd?} — see packages/backend/src/parent-app-v2/dto/publish-parent-app.dto.ts on the platform side. The server cross-checks the commitSha is reachable from branch and that your linked GitHub identity has push/admin on the repo. Re-publishing an existing friendlyName is only allowed if you were the original publisher (or an ACE admin).

Unpublish

scripts/unpublish-parent-app.sh <friendly-name>
# add `DELETE_REPO=1 … owner/repo` to also `gh repo delete` the source

Only the original publisher or a user with role=admin can unpublish.

E2E harness

scripts/e2e-parent-app-publish.sh drives the whole loop end-to-end for a Spring Boot (Java + Maven) + Next.js kit — scaffold, mvn compile smoke, gh repo create, publish POST, and round-trip verify via /api/parent-apps/:friendly and /api/parent-apps/resolve. The script preflights your linked GitHub account and bails early with an actionable message if it's missing. Use it as the reference implementation or as a smoke test before cutting a marketplace release; DRY_RUN=1 prints the payload without touching GitHub or the platform.

Quick Start

Production (acetoprod.com)

Use the hosted marketplace and (optionally) register the new app on your account.

• ace login must open the website origin — the CLI auth page is the SPA route /cli-auth on the frontend, not on the API host:

  ace login --platform-url https://acetoprod.com

• ace createapp <friendly-name> resolves templates via GET /api/parent-apps/resolve on the platform. Point at the API base (or the site if /api is proxied there):

  export ACE_PLATFORM_URL=https://api.acetoprod.com
  ace createapp my-starter-template ./my-app
  # or per command:
  ace createapp my-starter-template ./my-app --platform-url https://api.acetoprod.com

  Use the template’s friendly name from Find Your PaaS / Starter Apps. (Do not use the single word blank as the first argument here — the CLI reserves ace createapp blank <folder> for the offline “blank user app” path; use --blank for a local parent-app kit instead.)

Local default (OSS / localhost)

# 1. (Optional) Sign in to the ACE platform so `ace createapp` can register
#    the new app with your account. Skip for fully offline use.
ace login

# 2. (Optional) Verify your toolchain and install missing agent CLIs
#    (Cursor, Claude Code, pnpm, Node) with confirmation prompts.
ace doctor --install

# 3a. Clone a marketplace parent app. Runs `ace-setup.sh` and starts every
#     service in ace.json automatically — pass --no-setup / --no-run to skip.
ace createapp my-todo-kit my-app
cd my-app

# 3b. Or scaffold a blank parent-app kit instead.
ace createapp --blank my-parent-kit
cd my-parent-kit
pnpm install
pnpm dev   # launches DevLay Master; prompt the agent to build the kit

# 4. Resume services after stopping them (Ctrl-C restart loop).
ace run

After the services come up:

• Engine API: http://localhost:3002
• Customer backend: http://localhost:3000
• Customer frontend: http://localhost:5173
• DevLay UI: http://localhost:6008

What ace init Creates

When run without --template, the engine scaffolds a pnpm monorepo:

my-app/
  ace.json              # ACE configuration
  .ace/project.json     # Local project metadata
  .npmrc                # GitHub Packages registry for @ace/devlay
  package.json          # Monorepo root (Turborepo)
  pnpm-workspace.yaml
  turbo.json
  packages/
    backend/            # NestJS REST API (port 3000)
      src/main.ts
      src/app.module.ts
      src/app.controller.ts
      src/app.service.ts
    frontend/           # Next.js app (port 5173)
      app/layout.tsx
      app/page.tsx
    shared/             # Shared TypeScript types
      src/index.ts

Use --template <path> to copy from a custom template directory instead.

CLI Reference

Command	Description
ace login [--platform-url <url>]	Sign in to the ACE platform (browser-based OAuth).
ace createapp [<friendly> [<folder>]] [--type …]	Interactive app creation; --type blank|web|mobile or --blank; --open to launch browser after scaffold. For web, runs ace-setup.sh and starts all services automatically — add --no-setup / --no-run to skip.
ace init [<folder>] [--name <name>]	Offline alias for ace createapp --blank <folder>.
ace run [--dir <path>]	Start every service declared in ace.json (no per-service filter). Use it to resume services after stopping them; ace createapp <web-friendly> runs it for you the first time.
ace doctor [--install]	Check Cursor / Claude Code / pnpm / Node and optionally prompt to install.
ace update [--check] [--tag vX.Y.Z]	Self-update the ace binary from the latest GitHub release.

ace run always starts every service in ace.json — it's the "resume my app environment" command. There is no ace run <service> per-service restart; restart a service via its own process manager or the DevLay UI instead.

Architecture

ace-engine/
  src/
    main.rs             # CLI entrypoint, Clap argument parsing
    kine/
      init.rs           # `ace init` — scaffolding + template embedding
      run.rs            # `ace run` — service orchestration
    api/                # REST API (Axum, port 3002)
    ws/                 # WebSocket channels (/ws/main, /ws/stream, /ws/messages)
    agents/             # Agent trait + registry (Cursor, extensible)
    queue/              # Task queue manager
    storage/            # RocksDB persistence
    devlay_fallback.rs  # DevLay Master UI server (port 6008)
    templates/          # Embedded template files (NestJS + Next.js)

Agent Extensibility

The engine defines an Agent trait in src/agents/mod.rs:

#[async_trait]
pub trait Agent: Send + Sync {
    fn name(&self) -> &str;
    async fn execute_task(&self, task: &AgentTask) -> Result<AgentResult>;
    async fn cancel_task(&self, task_id: &str) -> Result<()>;
    fn is_available(&self) -> bool;
}

To add a custom agent:

1. Implement the Agent trait
2. Register it in AgentRegistry::new() in src/agents/mod.rs
3. Rebuild with cargo build

The default build includes Cursor support. Other agents (Qwen, Claude Code) exist behind configuration — they only activate when their respective environment variables are set.

DevLay

DevLay is the React developer overlay that ACE Engine serves. It provides:

• Agent chat with streaming output
• File explorer and editor
• Task queue management
• Project memory and rules
• Service logs
• Theme customization
• Plugin system for extensibility

DevLay is installed automatically from GitHub Packages when you run pnpm install in your app (the .npmrc in the template configures the @ace scope).

Configuration

ace.json

The main configuration file in your app root:

{
  "name": "my-app",
  "appId": "uuid-here",
  "services": {
    "backend": { "command": "pnpm dev:backend", "port": 3000 },
    "frontend": { "command": "pnpm dev:frontend", "port": 5173 }
  }
}

Environment Variables

Variable	Description
ACE_LOCAL_MODE	Set to 1 automatically by ace run for offline operation
ACE_DEVLAY_MASTER	Set to 0 to disable DevLay UI
ACE_DEVLAY_PACKAGE_PATH	Override path to @ace/devlay package
ACE_DEVLAY_MASTER_PORT	Override DevLay port (default: 6008)
CURSOR_API_KEY	Cursor agent API key

Cargo Features

Feature	Description
(default: none)	Minimal OSS build — everything needed for local development
cloud	Platform integration (used in commercial version)
tray	System tray icon (requires GTK on Linux)
gcs-backup	Google Cloud Storage backup support

License

MIT