Docs

OpenDock docs

OpenDock helps you add AI setup to a project, see what changed, update it later, and share your own dock when it is ready.

Install guide Open Hub

What OpenDock manages

A dock is a reusable AI workspace setup. It can add project instructions, prepare a project-local CLI tool, copy templates, or run a small check. You can install one dock, then add another when the project needs a new role or workflow.

Project state.opendock

opendock install opendock/codex@1.0.0
opendock install opendock/agent-ready@1.0.0
opendock install opendock/designer-ai@1.0.0
opendock install opendock/repo-context@1.0.0

.opendock/
  dock.lock.yml
  logs.jsonl
  workdirs/

OpenDock records what each dock added under .opendock/. That record is what makes update, doctor, and uninstall predictable later.

How setup is separated

OpenDock keeps machine-level setup, shared runtimes, project tools, copied-folder dependencies, command shims, and generated files in separate places. That is why a dock can install what it needs without turning the whole computer into one unmanaged script run.

Concept	Example	Managed by	Location
Runtime	`node`, `python`, `bun`, `git`, `uv`	OpenDock	`~/.opendock/runtimes/`
Package manager	`npm`, `bun`, `pnpm`, `pip`, `pip3`, `uv`	OpenDock during install	recorded in the project lock
Tool	`codex`, `claude`, `oma`, `eslint`	OpenDock	`.opendock/tools/`
Dependency	`node_modules`, `.venv`, `.opendock/python`	OpenDock	copied payload folder
Bin shim	`codex`, `oma`, `node`	OpenDock	`.opendock/bin/`
Workdir	a task folder where a tool generates files	task step	`.opendock/workdirs/` or project root

What happens during install

OpenDock downloads the reviewed dock release.
It prepares required runtimes, project tools, copied-folder dependencies, and .opendock/bin shims.
It applies files and exported workdir outputs.
It records the result in .opendock/dock.lock.yml so update, doctor, and uninstall can use it later.

Where things liveOpenDock

~/.opendock/
  runtimes/
    node/22.12.0/bin/node
    python/3.12.4/bin/python3
    bun/1.3.11/bin/bun

project/
  .opendock/
    bin/
      node    -> ~/.opendock/runtimes/node/22.12.0/bin/node
      npm     -> ~/.opendock/runtimes/node/22.12.0/bin/npm
      python3 -> ~/.opendock/runtimes/python/3.12.4/bin/python3
      oma     -> .opendock/tools/opendock__oma/oma/...
    tools/
      opendock__oma/oma/
    workdirs/
    dock.lock.yml
  .codex/skills/image2html/
    package.json
    node_modules/

Simple idea: runtimes are shared per user, while each project keeps its own shims, tools, workdirs, and lock records.

Commands

Most projects start with install, use doctor to check the setup, and use update or uninstall later. deploy is only for people publishing their own dock.

Command	Purpose
`opendock install owner/name@1.0.0`	Add a dock to the project you are in.
`opendock install owner/name@designer-build`	Install a named release, such as a beta or designer build.
`opendock install owner/name@1.0.0 --force`	Apply OpenDock changes even when local edits exist.
`opendock update`	Update installed docks when newer reviewed versions are available.
`opendock list`	Show docks installed in the current project.
`opendock list --json`	Print an installed dock inventory for tools.
`opendock outdated`	Check whether installed docks have newer reviewed versions.
`opendock update --force`	Update even when local edits exist.
`opendock install owner/name@1.0.0 --json`	Print a machine-readable change report. Update and uninstall also support this shape.
`opendock uninstall owner/name`	Remove one dock and the files OpenDock added for it.
`opendock uninstall owner/name --force`	Remove OpenDock files even when they were edited locally.
`opendock doctor`	Check the project and show what is installed.
`opendock doctor owner/name`	Check one installed dock.
`opendock log`	Show recent OpenDock activity for this project.
`opendock version`	Show the OpenDock CLI version.
`opendock auth login`	Log in before sharing a dock.
`opendock auth status`	Show who is logged in.
`opendock auth logout`	Log out on this machine.
`opendock deploy owner/name@1.0.0`	Send a local `dock.yml` release for OpenDock review.
`opendock deploy owner/name@1.0.0 --file dock.yml`	Send a specific manifest file for review.
`opendock deploy owner/name@1.0.0 --platform macos --file dock.macos.yml`	Submit a release file for a specific OS.
`opendock <command> --help`	Show options and usage for a specific command.

Dock names

When you install or share a dock, type its name with a version after @.

Reference	Result
`owner/name`	Rejected: missing version.
`owner/name@latest`	Rejected: choose a real version instead of latest.
`owner/name/extra@1.0.0`	Rejected: dock names use owner/name.
`owner/name@1.2.0`	Accepted: reviewed version.
`owner/name@designer-build`	Accepted: named reviewed version.

opendock update does not need a dock name. It checks what is already installed and updates docks that have a newer reviewed version.

Write dock.yml

A dock.yml file describes the setup package. Keep it direct: catalog text for people, files for project content, tools for project-local CLIs, dependencies for packages inside copied folders, and install/update/doctor for ordered tasks.

dock.ymlWorkspace dock example

opendock: 1
summary: UI, UX, product design, design system, Figma workflow, and review templates.
readme: DOCK.md
logo: logo.png
tags:
  - design
  - ux
  - figma
  - product

files:
  - from: files/AGENTS.md
    to: AGENTS.md
  - from: files/CLAUDE.md
    to: CLAUDE.md
  - from: files/GEMINI.md
    to: GEMINI.md
  - from: files/.codex/skills/opendock-designer-ai/SKILL.md
    to: .codex/skills/opendock-designer-ai/SKILL.md
  - from: files/.claude/skills/opendock-designer-ai/SKILL.md
    to: .claude/skills/opendock-designer-ai/SKILL.md
  - from: files/PROMPTS.md
    to: PROMPTS.md
  - from: files/DESIGN.md
    to: DESIGN.md
  - from: files/DESIGN_SYSTEM.md
    to: DESIGN_SYSTEM.md
  - from: files/UX_REVIEW.md
    to: UX_REVIEW.md
  - from: files/FIGMA_WORKFLOW.md
    to: FIGMA_WORKFLOW.md

doctor:
  - id: agents-md
    check: test -f AGENTS.md
  - id: codex-skill
    check: test -f .codex/skills/opendock-designer-ai/SKILL.md
  - id: claude-skill
    check: test -f .claude/skills/opendock-designer-ai/SKILL.md
  - id: design-md
    check: test -f DESIGN.md
  - id: design-system
    check: test -f DESIGN_SYSTEM.md
  - id: ux-review
    check: test -f UX_REVIEW.md
  - id: figma-workflow
    check: test -f FIGMA_WORKFLOW.md

This example is shortened from the real opendock/designer-ai dock. A role dock usually adds team instructions, agent skill files, and working templates, then uses doctor to confirm they are present.

dock.ymlTool dock example

opendock: 1
summary: Tool dock for installing the Codex CLI without project payloads.
readme: DOCK.md
logo: logo.png
tags:
  - codex
  - tool
  - ai-agent
requires:
  runtimes:
    node: ">=22.0.0"
    npm: ">=10.0.0"
tools:
  codex:
    manager: npm
    package: "@openai/codex"
    version: latest
    commands:
      - codex

doctor:
  - id: check-codex
    run: codex --version

Dock names and release versions are added when you share a dock, for example opendock deploy opendock/designer-ai@1.0.0. They do not need to be written inside dock.yml.

readme, logo, and tags are the parts people see first in Hub. Use them to explain what the dock is for.

Field	Required	Meaning
`opendock`	Yes	`1` is the supported manifest version.
`name`, `summary`	No	Human-facing metadata. It does not change runtime behavior.
`readme`	No	Safe relative path to a Markdown file, such as `DOCK.md`. `opendock deploy` uses it for the dock detail page and rejects files larger than 65536 bytes.
`logo`	No	Safe relative path to a PNG, JPEG, or WebP image, such as `logo.png`. `opendock deploy` checks the image format, uses it as the Hub logo, and rejects files larger than 524288 bytes.
`tags`	No	Short lowercase labels for Hub search and filtering, such as `design` or `ai-agent`. They only help people find the dock and do not change install, update, uninstall, or doctor behavior.
`permissions`	No	Exact task command shapes allowed beyond the small default policy. New docks should use `permissions`; `permission` is accepted for compatibility, but do not use both.
`requires`	No	Runtime requirements prepared before manifest tasks.
`tools`	No	Project-local CLI packages OpenDock installs and tracks under .opendock/tools.
`dependencies`	No	Package dependencies installed inside folders copied by the dock, such as a Codex skill or harness folder.
`workdir`	No	Input files copied into the dock-private workdir before tasks run.
`files`	No	Explicit file mappings applied to the project root.
`install`, `update`, `doctor`	No	Manifest tasks for setup, refresh, and health checks.

Requirements

requires.runtimes is for runtimes a dock needs before tasks run. OpenDock prepares runtimes under the user's ~/.opendock/runtimes/ directory and creates project .opendock/bin/ shims. CLI packages such as Codex or Claude Code belong in tools. Package dependencies for a folder copied by the dock belong in dependencies.

dock.ymlRuntime and tool declaration

requires:
  runtimes:
    node: ">=22.0.0"
    npm: ">=10.0.0"

tools:
  codex:
    manager: npm
    package: "@openai/codex"
    version: latest
    commands:
      - codex

doctor:
  - id: check-codex
    run: codex --version

dock.ymlPython CLI tool with uv

tools:
  ruff:
    manager: uv
    package: ruff
    version: latest
    commands:
      - ruff

dock.ymlCopied folder dependencies

requires:
  runtimes:
    node: ">=22.0.0"
    npm: ">=10.0.0"

files:
  - from: image2html
    to: .codex/skills/image2html

dependencies:
  image2html:
    manager: npm
    path: .codex/skills/image2html
    mode: locked

A simple way to choose: use tools for commands OpenDock should expose, and use dependencies for packages needed inside a folder the dock copied into your project.

install is the normal choice when the copied folder has no lockfile or can accept compatible package updates.
locked is for folders that ship a lockfile and should reproduce the same dependency set.
uv works in both places: as a tool manager for CLI packages and as a dependency manager for copied Python project folders.

OpenDock does not let a dock run arbitrary shell commands. Task run and check are split into a command and arguments, then checked against a small policy.

Allowed by default: bun, git, node, npm, pip, pip3, pipx, pnpm, python, python3, test, uv. The safe shapes are intentionally small, such as version checks, git status, git init -b main, and test -f.
Windows adds a limited powershell file check shape.
Declare non-default CLIs in tools.commands first. Use permissions only for the exact task shape that command may run.
Package install and update commands such as npm install, bun add, pip install, pipx install, uv tool install, brew install, and winget install are rejected in tasks. Put project tools under tools and copied-folder package dependencies under dependencies.
Rejected shell operators: |, &&, ||, ;, backticks, $(, >, <.

Area	Behavior
`requires.runtimes`	Checks supported runtime versions: `bun`, `git`, `node`, `npm`, `uv`, `pip`, `pip3`, `python`, and `python3`. Install and update can install known missing or outdated runtimes when OpenDock has a supported installer.
`tools`	Installs and tracks project-local CLI tools with `npm`, `bun`, `pnpm`, `uv`, `pip`, or `pip3`, then exposes declared commands through `.opendock/bin/` shims.
`dependencies`	Installs package dependencies inside folders copied by the dock. Supported managers are `npm`, `pnpm`, `bun`, `uv`, `pip`, and `pip3`. Use `install` for normal installs and `locked` when a lockfile or frozen environment should be respected.
`doctor`	Reports requirement status without installing or modifying the host.
`install`, `update`, `doctor`	Runs installed tools only when a project action or generated output is needed.

Files and ownership

files says which files from the dock should be added to the project. OpenDock keeps those changes tracked so future updates can be applied or removed safely.

Field	Required	Meaning
`from`	Yes	Source file or directory path relative to the dock root, such as `files/DESIGN.md` or `files/AGENTS.md`.
`to`	Yes	Target path relative to the project root, such as `AGENTS.md`.

readme, logo, and tags are for the Hub listing. readme and logo files are copied into a project only when they also appear under files.

Automatic ownership modes

OpenDock chooses the safest update method for each file. Text files get an OpenDock block, while images and config files are protected with checksums.

Mode	Use	Behavior
Text managed block	`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.md`, `.txt`	Adds or updates an `OPENDOCK:START` block and leaves user content outside the block untouched.
Checksum-protected file	Images, config files, binary files, and files that cannot safely contain markers	Replaces or deletes the file only when the current checksum still matches the last OpenDock-applied checksum.

Tasks and steps

Tasks are the moments when a dock does work: first install, later update, and health check. A manifest supports only install, update, and doctor tasks. Uninstall is handled by OpenDock from the recorded files and tools.

Field	Required	Meaning
`install`	No	Runs during first install for initial project actions or generated outputs.
`update`	No	Runs when installed docks move to newer reviewed versions.
`doctor`	No	Checks current project and tool state without installing tools or changing files.

Field	Required	Meaning
`id`	Yes	Step identifier shown in logs and doctor output.
`name`	No	Human-readable step label. OpenDock falls back to the id when it is omitted.
`check`	No	Command used to detect whether the step is already ready.
`run`	No	Command run when install or update needs to change state.
`version`	No	Semver range checked against the first x.y.z version found in command output.
`timeout_ms`	No	Positive command timeout in milliseconds. Doctor defaults to 30000ms.
`workdir`	No	`root` runs in the project root. `dock` runs in `.opendock/workdirs/<dock>/`. The default is `root`.
`export`	No	When `workdir: dock` is used, selects generated files with `include` and `exclude` globs and applies them to the project root.
`platforms`	No	Optional per-step overrides for supported platforms such as `macos`, `windows`, or `linux`.

dock.ymlWorkdir files and export

permissions:
  - node scripts/build-repo-context.mjs

workdir:
  files:
    - from: workdir/build-repo-context.mjs
      to: scripts/build-repo-context.mjs
    - from: workdir/context-template.md
      to: templates/context-template.md

install:
  - id: build-repo-context
    run: node scripts/build-repo-context.mjs
    workdir: dock
    export:
      include:
        - AGENTS.md
        - README.md
        - .opendock/context/**
        - .codex/skills/opendock-repo-context/**
      exclude:
        - "**/*.log"
        - "**/cache/**"

update:
  - id: refresh-repo-context
    run: node scripts/build-repo-context.mjs
    workdir: dock
    export:
      include:
        - AGENTS.md
        - README.md
        - .opendock/context/**
        - .codex/skills/opendock-repo-context/**

doctor:
  - id: repo-context
    check: test -f .opendock/context/README.md

Hub deployment

Use Hub to find a dock that matches your project. Public docks are reviewed before release and can be installed without signing in. Sign in only when you want to publish your own dock.

TerminalShare a dock

opendock auth login
opendock deploy opendock/my-dock@1.0.0 --file dock.yml

Release files

When a dock needs different setup per OS, submit a separate manifest file for each platform with --platform and --file. Names like dock.macos.yml are a helpful convention, not a required rule.

TerminalOS-specific releases

opendock deploy owner/name@1.0.0 --platform macos --file dock.macos.yml
opendock deploy owner/name@1.0.0 --platform windows --file dock.windows.yml
opendock deploy owner/name@1.0.0 --platform linux --file dock.linux.yml

If --platform is omitted, OpenDock uses the current host OS. The important part is the file passed to --file; install remains simple: users still run opendock install owner/name@1.0.0.

Try a dock in a temporary project first. When the setup feels right, combine the docks you need and share your own dock for review.

TerminalOpenDock

opendock install opendock/codex@1.0.0
opendock install opendock/agent-ready@1.0.0
opendock install opendock/designer-ai@1.0.0
opendock install opendock/repo-context@1.0.0
opendock doctor
opendock doctor opendock/designer-ai
opendock update
opendock uninstall opendock/designer-ai
opendock auth login
opendock deploy opendock/designer-ai@1.0.0