Nucleus Configuration

NUCLEUS.md is a configuration file that customizes how Nucleus behaves. It lets you define workflows, skip confirmation prompts, and set up post-launch automation — all in plain Markdown.

It is stored on the server, against your account, so it follows you to another browser, another machine and another session. It is personal, not shared with your team: teammates each have their own, and nobody else can read yours.

Which file do I want?

NUCLEUS.md configures the assistant you talk to in the dashboard — the one that answers in chat and acts only when you ask. For the agent that executes your Runs, Schedules and Loops in the background, including unattended firings with no browser open, you want NOVA.md instead. Two different agents, two different files; neither one reads the other’s, and both are stored against your account.

Wrote one before this changed?

NUCLEUS.md used to live in your browser’s local storage, which meant it stayed behind on the machine you wrote it on. Any file still sitting in a browser is carried onto your account automatically the first time that browser opens Settings or sends a Nucleus message — you don’t need to copy anything across. If you had already written a different file on your account by then, the account version is kept and the leftover browser copy is discarded.

Where to Edit

NUCLEUS.md is managed in the orchestrator dashboard:

1. Open the orchestrator at your deployment URL
2. Go to Settings → App AI Assistants
3. Find the NUCLEUS.md block, above the NOVA.md one
4. Click Edit NUCLEUS.md

Nucleus applies your NUCLEUS.md to every message you send. The editor shows a live character count against a limit of 10,000 characters, plus an estimate of the tokens your file adds to every Nucleus message. Past the limit the counter turns red and Save tells you how much to trim instead of writing — your text is left exactly as you typed it, never silently truncated.

How It Works

When Nucleus receives a message, it loads your NUCLEUS.md content as mandatory instructions that override its default behavior. Nucleus will execute every step you define in order — it won’t skip steps or stop early. Safety requirements (confirming destructive operations like stop/remove) still take priority.

Directives

Auto-Launch

By default, Nucleus shows a launch summary and waits for your confirmation before creating a DevBox. Add the auto-launch directive to skip the confirmation:

## Launch Settings

auto-launch

With auto-launch enabled, Nucleus still resolves all values (worker, image, name) and shows a brief summary, but proceeds immediately without waiting for “yes.”

Post-Launch Workflow

Define what Nucleus should do automatically after launching a DevBox. Without a workflow, Nucleus asks if you’d like to open a terminal. With a workflow, it executes your steps instead:

## Post-Launch Workflow

1. Start Claude Code in the DevBox with `--dangerously-skip-permissions`
2. Open the terminal so I can watch

Nucleus will follow these steps sequentially after a successful launch.

Example

Here’s a complete NUCLEUS.md that auto-launches DevBoxes and starts the AI agent automatically:

## Launch Settings

auto-launch

## Post-Launch Workflow

1. Start Claude Code with --dangerously-skip-permissions
2. Open the live terminal

## Preferences

- Always use terminal images, not display images
- Default to 8 GB memory for DevBoxes
- When I say "go", treat it as a launch request

Improving your draft

The editor carries the sparkle (✦) — the prompt improver. Because this field holds a standing configuration rather than a one-off job, the sparkle here runs the system-prompt rewrite: it regroups your directives and preferences under your own headings, keeps your voice and your naming templates, and never turns “be more concise” into a numbered work order. The instruction rewrite — goal, steps, what “done” means — is what the same sparkle does in the Nucleus chat composer, or in a Run or Schedule field. Accept replaces the draft; Discard leaves it exactly as you typed it.

Tips

• Keep instructions clear and actionable — Nucleus follows them literally
• Use numbered lists for sequential workflows
• The Preferences section is free-form — Nucleus interprets it as behavioral guidance
• You can reset to defaults at any time from the Settings page
• Changes take effect on the next Nucleus message — no restart needed

Next

• Nucleus — what the chat assistant does.
• NOVA.md — the standing file for the coordinator that executes your Runs, Schedules and Loops, unattended if need be.
• Prompt improver — the ✦ on this editor, and why it rewrites this field differently from a chat message.
• Settings — the rest of the App AI Assistants section.