agentleFS
onyx-dot-apponyx-dot-app/onyx-foss/.agents/skills/onyx-dev-stack/SKILL.md

onyx-dev-stack

Skill320 starsChanged 8 days agoMITView on GitHub

Start, inspect, restart, or stop an Onyx development stack with ODS. Prefer frontend-only previews for frontend-only diffs, shared infrastructure for ordinary work, and explicit isolation for independent datasets. Do not use for Kubernetes development.

  • Reads credentials

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. onyx-dot-app/onyx★ 33k88% same

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository10 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. About 0 are common, 9 are distinctive, and 17 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 17

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run from the worktree that contains the code being tested.

    line 8
  2. Very specific:

    Check for uv, bun, and a running Docker daemon.

    line 12
  3. Very specific:

    Check ods web dev --help and ods --help too.

    line 18
  4. Very specific:

    Use the selected command for the remaining steps.

    line 27
  5. Very specific:

    If a matching frontend already runs in this checkout, ODS attaches instead.

    line 39
  6. Very specific:

    Use the reported web URL for browser tests and HTTP requests.

    line 58
  7. Distinctive:

    If the database is already at head, unchanged healthy services keep running.

    line 62
  8. Distinctive:

    Run a slow startup in a background terminal when available.

    line 64
  9. Very specific:

    Read "$ODS" stack up --help before choosing a different profile:

    line 66
  10. Very specific:

    Use --local-model-server only when changing model-server code.

    line 72
  11. Very specific:

    Use ods --isolated stack up for separate state, ports, Compose projects, databases, queues, indexes, and object storage.

    line 79
  12. Very specific:

    Use ods web dev for frontend-only diffs with a healthy managed API.

    line 80
  13. Very specific:

    Stop managed services before manual db upgrade or db downgrade.

    line 89
  14. Distinctive:

    Do not stop another worktree's services or kill unrelated processes to free a port.

    line 91
  15. Very specific:

    Keep .vscode/.env and .vscode/.env.web untracked.

    line 92
  16. Distinctive:

    Use shared mode for sequential development and frontend previews.

    line 94
  17. Very specific:

    If the stack starts on unexpected ports, or Docker resources run low, run "$ODS" stack ls --all to see the other stacks on the machine.

    line 105
  18. Very specific:

    Run "$ODS" stack logs --help to select a service or follow logs.

    line 107
  19. Very specific:

    Use disposable worktrees with ods --isolated stack up for these tests.

    line 114
  20. Distinctive:

    Never reset a developer database to satisfy a test fixture.

    line 116
  21. Distinctive:

    Stop managed application processes while keeping infrastructure available:

    line 121
  22. Distinctive:

    Stop the worktree's application processes and infrastructure:

    line 127
  23. Distinctive:

    After shutdown, inspect status to confirm the targeted stack stopped.

    line 135
  24. Very specific:

    Run "$ODS" stack ls from any directory.

    line 139
  25. Very specific:

    Stop orphaned stacks; no worktree owns them.

    line 141
  26. Very specific:

    Do not add --force, prune --yes, or prune --volumes unless the user asks.

    line 142

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Onyx dev stack

Run from the worktree that contains the code being tested. ODS owns processes, ports, state, and logs.

Select ODS

Check for uv, bun, and a running Docker daemon. Use the repository-pinned ODS when it provides the stack command:

uv run --frozen --only-group ods ods stack --help

Check ods web dev --help and ods --help too. If the pinned package lacks the shared-stack behavior, build ODS from this checkout. This requires Go:

ODS_BUILD_DIR="$(mktemp -d "$(git rev-parse --path-format=absolute --git-path ods-stack-bin).XXXXXX")"
ODS="$ODS_BUILD_DIR/ods"
go -C tools/ods build -o "$ODS" .
"$ODS" stack --help

Use the selected command for the remaining steps. Examples below use "$ODS"; replace that prefix with the pinned invocation when available.

Start and discover

For frontend-only diffs on macOS or Linux, run the frontend against an existing healthy managed API:

"$ODS" web dev

This foreground command starts only the web server. Keep its terminal running. It requires a healthy managed API. Ctrl-C stops a newly launched preview. If a matching frontend already runs in this checkout, ODS attaches instead; Ctrl-C then only detaches. stack status does not list standalone previews. Ctrl-C also cancels dependency installation and library builds during startup. It does not run migrations, start workers, or start containers. If no healthy API exists, start the default stack first. Use a full stack for backend changes and OAuth callback testing, because the reused API retains its original web origin. Other ods web scripts, including build and test, remain package-script commands.

On Windows, web dev and backend use portable foreground launchers and configured connection variables. Managed stacks, API discovery, and attachment are macOS/Linux behavior. Check the frontend URL directly after a Windows launch.

For ordinary work, start the default profile with shared infrastructure:

"$ODS" stack up --timeout 12m
"$ODS" stack status --json

Use the reported web URL for browser tests and HTTP requests. Do not assume port 3000 or call a backend port directly.

up prepares local environment files and dependencies, reuses shared infrastructure, applies migrations, and reconciles background application services. Existing secrets stay private. Ask for a model key only when the requested test needs one. Pending migrations stop managed application services before changing the schema. If the database is already at head, unchanged healthy services keep running.

Run a slow startup in a background terminal when available. Wait for its exit and inspect status before reporting success.

Read "$ODS" stack up --help before choosing a different profile:

  • minimal runs web and API for UI/API work.
  • default adds the workers needed for ordinary indexing and background tasks.
  • full runs the full launch compound for integration work.

Use --local-model-server only when changing model-server code. Other profiles use Compose inference and avoid a duplicate local model process. Repeat the profile and local-model flag with start or restart. Use up to change model mode or recover infrastructure.

Multiple agents

  • Agents in the same worktree share one stack. Reuse a healthy stack through up and status.
  • By default, worktrees share infrastructure and one active application checkout. Running up elsewhere stops the prior managed app before migrations.
  • Use ods --isolated stack up for separate state, ports, Compose projects, databases, queues, indexes, and object storage. Repeat --isolated for later commands.
  • Use ods web dev for frontend-only diffs with a healthy managed API. Its Ctrl-C behavior leaves the reused API running.
  • Shared status reports the active checkout. Run stop, down, start, and restart there. Only up transfers ownership.
  • Legacy datasets are preserved. If several exist at first shared startup, select the intended one with --project; never choose by timestamps. Stop its legacy stack with --isolated before adoption.
  • Legacy discovery reads saved ods stack state. Compose-only setups need their previous --project NAME explicitly. Use ods --project NAME stack up to save that shared selection before using the default commands.
  • Project ownership is durable. An explicit project collision fails, including in isolated mode. Select a different project for independent infrastructure.
  • ODS keeps a stack's ports while it runs. stop releases the application ports (web, API, MCP, model, metrics) and keeps the infrastructure ports. down releases all of them. Another stack can reclaim the ports of a stopped stack, and a stopped stack moves back to the lowest free port. Read status again after a restart or start.
  • The selected stack lock coordinates lifecycle changes. Shared handoffs serialize; isolated stacks can start independently.
  • Foreground services and full stacks use the same service specifications and process launchers. A full stack replaces a same-checkout preview and retains its port.
  • Database operations target exact project containers and use state/project locks. Do not work around a target conflict or another checkout's ownership guard.
  • Stop managed services before manual db upgrade or db downgrade. Use stack up for pending-aware upgrades.
  • An explicit loopback database port resolves to its actual managed owner. ods env leaves dotenv files unchanged if the selected Postgres container has no published port.
  • Do not stop another worktree's services or kill unrelated processes to free a port.
  • Keep .vscode/.env and .vscode/.env.web untracked. Do not print their contents.

Use shared mode for sequential development and frontend previews. Use isolated mode for simultaneous backend branches, incompatible schemas, destructive tests, or independent datasets.

Inspect and recover

"$ODS" stack status --json
"$ODS" stack logs

Inspect the reported phase, failed services, and logs when startup is incomplete. Re-run up to recover a partial start. Preserve healthy services and report optional integrations that remain unavailable.

If the stack starts on unexpected ports, or Docker resources run low, run "$ODS" stack ls --all to see the other stacks on the machine.

Run "$ODS" stack logs --help to select a service or follow logs. Follow logs in a background terminal when continued observation is needed.

Successful startup requires the readiness check through the reported frontend URL. A process that exists is insufficient evidence.

Validate changes

For lifecycle, concurrency, browser, or real worker validation, read the ODS integration guide. Use disposable worktrees with ods --isolated stack up for these tests. They create accounts, change the default test LLM provider, and stop services. The browser smoke configuration supports an unlicensed local deployment. Its chat checks use a scripted local LLM, not a paid model key. Never reset a developer database to satisfy a test fixture. Database restore errors fail the command; SQL restores stop on SQL errors.

Stop

Stop managed application processes while keeping infrastructure available:

"$ODS" stack stop

Stop the worktree's application processes and infrastructure:

"$ODS" stack down

Normal shutdown preserves volumes. Delete database, index, or object-store data only when the user explicitly requests a reset.

After shutdown, inspect status to confirm the targeted stack stopped. Check that another running worktree remains available when testing isolation.

Find and stop old stacks

Run "$ODS" stack ls from any directory. It lists every stack on the machine and prints the command that stops each one. Add --all for stopped stacks, --json for the same rows with a next field. Run "$ODS" stack ls --help for the statuses.

Stop orphaned stacks; no worktree owns them. Run the printed command, or confirm with the user before you stop a stack that another agent may still use. Do not add --force, prune --yes, or prune --volumes unless the user asks.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.