shipgremlins. GitHub

WELCOME TO THE CREW

Adopt your first
gremlin.

A curious little creature. A real product responsibility. Start with the app you already build, give your crew useful responsibilities, and approve the improvements worth pursuing. ShipGremlins runs on your own computer or server.

New projects use managed delivery: approve an epic, let the crew implement and QA its tickets, then review each PM’s promotion batch into staging. Adoption saves a brief. Activation starts ready patrols and eligible coding; neither approves an epic.

Your first adoption

Have Node.js 22.12+, Git, and Docker with Linux containers ready. Run these commands on the computer or server where your gremlins will work:

npm install -g git+https://github.com/AgentBurgundy/shipgremlins.git
gremlins setup

A private dashboard opens in your browser. Keep the terminal running while you get started. This installs your own workspace; there is no hosted account to sign up for. On a server, use gremlins setup --lan and open its printed session link.

  1. Connect the app you already have. Open Projects → Add project and choose Improve my app. Connect its GitHub or GitLab repository. A working prototype is enough.
  2. Prepare the crew’s tools. Connect Claude Code and create or resume a verified Docker worker. Your setup progress links to the missing connection or runner.
  3. Let AI inspect the source. A Setup Gremlin reads a bounded selection of actual code. Review suggested install and check commands, then choose Confirm setup. Inspection proposes settings; it does not run commands or prove the app works.
  4. Review your suggested crew. AI proposes up to four distinct responsibilities grounded in that inspection. Meet and adopt the useful gremlins one at a time. The remaining suggestions stay under Your crew; another scan is not required. You can edit each brief or write your own. Adoption leaves automation paused.
  5. Give each PM a place to work. Connect Linear and select the app’s team. Set up Linear prepares missing PM projects and labels, preserving existing mappings. Connect optional Sentry, Datadog, or Mixpanel signals now or later.
  6. Test the app they will use. Connect Vercel and select the repository’s preview, or choose another test host. A saved Vercel project needs no extra test URL. If important flows require login, connect a dedicated app account and run Test environment. Repository-only projects can continue without hosting.
  7. Activate the ready crew. Choose Activate ready crew after all required checks pass. PMs investigate on their schedules. Coding waits for work inside an owner-approved epic; activating is not approval.

The setup checklist survives returning to the project and points to the next unfinished step. Browser patrols require a passed check of the current environment and app access, alongside source, AI, Linear, and worker readiness. A saved token or reachable URL alone is insufficient. Read-only Discovery can run earlier with source, Claude Code, and a ready worker; it does not require Linear or hosting.

Vercel access and app sign-in are two different doors. Connecting Vercel gets a browser through preview protection. It does not log a gremlin into your product. Choose a dedicated password test account or explicitly choose Public pages only; public-only coverage leaves account, billing, and other private flows untested.

Try one improvement → · Installation details → · Experimental idea builds →

When should you bring in ShipGremlins?

When your existing app has more opportunities than you have time to pursue. Give one neglected flow a clear outcome. Your crew learns the product, investigates gaps, and implements approved work. You set priorities and review changes.

Where you areA useful next step
An early codebase or working prototypeStart with one PM’s repository discovery. Give it a concrete area and review its feature map and suggested opportunities. A public launch is not required.
An app with more work than you can keep up withUse a patrol to investigate a neglected flow, approve a bounded epic, and let the crew implement and QA its milestones before reviewing a promotion batch.
A product with several areas to maintainAdd distinct PM mandates and schedules as needed. Keep work limits within your capacity to review the results.

The trigger is your development workload. You don’t need paying users, a funding milestone, or a large team. A solo builder or small team can start with one area that deserves more attention.

What to bring

Keep using your editor and coding tools for hands-on changes. Your crew supplies ongoing responsibilities, shared direction, and a repeatable review process as the app grows.

Your first improvement: approve an outcome

  1. Pick a flow you already have. For example, “Help users import a CSV and understand which rows were accepted.” Define the expected outcome and what the PM should leave alone.
  2. Inspect, then adopt one PM. Import the repository, review the Setup Gremlin’s suggested commands, and confirm your selected settings. Choose the PM’s job, meet the gremlin, and review its name and brief. Your original goal stays its mandate. Save the adoption with automation off; connect optional project signals or skip them.
  3. Let it learn. Choose Explore the codebase for Discovery with source access, Claude Code, and a ready Docker worker. Prepare first mission opens the checklist if any of these are missing. Review the feature map and opportunities. Linear and hosting can come later; discovery does not file tickets.
  4. Investigate an outcome. Connect Linear and, for browser work, isolated staging. Start a mission from the project home. The PM can prepare missing Linear mappings and labels using your selected account; existing mappings stay in place.
  5. Approve a bounded epic. Read its outcome, evidence, exclusions, and acceptance criteria. Approval records the exact scope you reviewed. The PM then creates testable child tickets inside it. Changed epic scope needs new approval; a PM-added label alone cannot grant it.
  6. Let the crew complete the loop. Coders pick up eligible child tickets. The controller checks and merges internal PRs into pm-staging. Each owning PM tests its changed behavior; failures return to coding with Linear feedback and bounded retries.
  7. Review a promotion batch. Each PM collects passing tickets into its own PR to staging, at 10 tickets by default. Review the combined change and evidence there. You still decide when staging goes to production.

A good first win: a concrete improvement with evidence you can inspect and a change you can review. Start small enough to judge the result before giving the crew more work.

Keep an improvement together

On the project home, What should get better? starts an improvement mission. It keeps the outcome, investigation, proposed tickets, approved plan, runs, and review links together. The home page brings changes ready for review and blocked work ahead of the next assignment.

A mission uses your existing PM and runner queue. If the project has no PM, it can prepare a focused one with recurring work off. With the new managed policy, investigation proposes an epic for owner approval; the PM decomposes approved scope into child tickets. Recorded dependencies must be satisfied before coding proceeds, and existing work is reused instead of starting a duplicate implementation. Existing projects retain their configured approval policy.

Coding receives the PM’s product brief, owner context, and accepted criteria. Its draft describes what changed, what the worker checked, and what remains unverified. Model-authored explanations do not replace independent verification. Missing integrations and mocks must be called out.

Investigation and coding have separate controls

Enable scheduled PM patrols when you want recurring investigation. Enable automatic coding pickup when you want approved, ready tickets to run on eligible workers. You can use either independently, or leave both off and start a single run. WIP limits, project budgets, approval checks, and dependency holds still apply.

Ask a Grumblin to try it again

A Grumblin is an AI-generated, simulated customer with a relevant goal and personality. Its real browser observations are evidence of that walkthrough; its preferences are hypotheses. Retained journey snapshots let you revisit the same profile after a change. A before/after comparison is useful evidence, not proof of customer demand or a causal conversion lift.

Mission and pilot guide →

Experimental: start with an idea

Improving existing applications is the main workflow. Idea builds establish a foundation and need iteration. Passing checks or a working scaffold do not prove a polished product; inspect the design, real integrations, and complete journey before accepting the result.

  1. Describe the first useful version. In Projects → Add project, choose Start from an idea · experimental. The guided setup asks one question at a time. Explain who it is for, what they need to do, and what can wait. Connect Claude Code and have Docker available on the controller.
  2. Plan my crew. Review the first milestone and one to four proposed PMs. Each gets a distinct mission, a first assignment, and acceptance criteria. A foundation PM owns the shared app; other PMs depend on that foundation. Edit the idea and plan again to change the scope.
  3. Give it a home. Name the project, choose GitHub or GitLab and its owner, then review visibility. Private is selected by default. Choose public explicitly for open-source work; public visibility does not add a license. The final review shows the new repository, visibility, crew, and milestone. ShipGremlins creates the repository, adds the reviewed brief, and saves the PMs with automation paused. Configure Linear and workers afterward.
  4. Resume if access needs attention. GitHub repository creation needs Administration write access (or Repository creation write where available), plus installation access to the new repository. Accept updated app permissions if prompted. GitLab needs API access and permission to create in the chosen namespace. If setup stops, resume the same plan; an existing unrelated repository is never adopted or overwritten.
  5. Build the foundation first. Open the project’s Environment page and review the first coding assignment. Approve & build foundation prepares Linear, checks the selected connections, and queues a Coding Gremlin for that exact scope. Inspect its draft PR or MR, review the checks, and merge the foundation. Then check for application code and choose a test environment. PMs do not patrol an empty repository.

The crew is created together; implementation is reviewed step by step. The starting stack is Node.js with npm. Crew creation does not generate application code or deploy it. Dependency order is recorded in PM briefs, and you run the remaining PMs as their prerequisites become available. Retry the same saved plan and destination if setup stops partway through.

Try: “A booking app for a pottery studio. Students browse classes and reserve a seat; the owner manages sessions and capacity. First version: bookings, no online payments.” Read the idea onboarding guide →

1. Install the global CLI

You need Node.js 22.12 or newer, Git, and Docker with Linux containers. Install once, then open your private setup dashboard. Works with PowerShell, macOS, and Linux:

npm install -g git+https://github.com/AgentBurgundy/shipgremlins.git
gremlins setup

The dashboard opens locally in your browser. Add your app and enter connection tokens there. Saved values stay on the machine running ShipGremlins. Adding a project does not start a PM or Coding Gremlin or enable automation. Importing an existing app may start a Setup Gremlin analysis when source access and Claude Code are ready.

This installs the official GitHub source as a global command. The package is not published to the npm registry yet, so keep the full Git URL. You do not need to clone or fork the repository, and you can run gremlins from any directory.

On a server or homelab?

Run this on the machine that will host your workers. Open the private session link printed by the CLI from a browser on your trusted network:

gremlins setup --lan --port 4311

Port 4311 is the dashboard’s default. Credentials, configuration, Docker, and jobs live on that server. Treat its session link as a password; keep this HTTP endpoint on a trusted private network, not the public internet. The in-browser configuration editor works remotely too.

For a persistent server, use the background controller. It stays up after you close the terminal; status prints your private dashboard link again:

gremlins start --lan --port 4311 --no-open
gremlins status
gremlins stop

gremlins setup stays in the foreground until Ctrl+C. gremlins stop stops scheduling while running Docker jobs finish. To start automatically after a reboot, configure systemd, launchd, or Windows Task Scheduler on your host.

Private network access

Allow port 4311 only from your trusted subnet if your firewall requires it. ShipGremlins does not change firewall rules. Use the complete printed session link on the first visit; the dashboard removes its session fragment after it opens. A bare address is not a login, and this is a private operator dashboard rather than a public multi-user service.

For an SSH tunnel instead of a LAN listener, run the first command on your server and the second on your laptop, then open the server’s loopback session link:

gremlins dashboard --no-open --port 4311
ssh -L 4311:127.0.0.1:4311 USER@SERVER_IP

Start after a server reboot

The background command survives closing a terminal; it does not install an operating-system startup service. On Linux, supervise the foreground dashboard with a systemd user service. Find your actual executable paths with command -v gremlins and command -v node.

Save the following as ~/.config/systemd/user/gremlins.service, replacing YOUR_USER, the CLI path, and PATH for your installation:

[Unit]
Description=ShipGremlins local controller
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
Environment=PATH=/home/YOUR_USER/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/YOUR_USER/.local/bin/gremlins --home /home/YOUR_USER/.shipgremlins dashboard --lan --port 4311
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now gremlins.service
journalctl --user -u gremlins.service -n 30

Docker must start with the host, and the service user must have Docker access. Include Node’s directory in PATH, especially with a version manager. Stop any manually started controller using the same port first. For a user service without interactive login, enable lingering with loginctl enable-linger YOUR_USER using your host’s required permissions. The private session link appears in that user’s service log.

Windows Task Scheduler and macOS launchd are separate host setup steps. After a host reboot, interrupted agents are reconciled as failed rather than silently replayed. Review their activity before asking for another run.

Connect your code with GitHub or GitLab

Open Source control in your dashboard and choose Connect GitHub or Connect GitLab. ShipGremlins uses the official provider’s device authorization flow. You approve access in your own browser; the dashboard never asks for your account password.

  1. Copy the verification code shown in the dashboard.
  2. Open the provider approval link in its new tab. Confirm the code, account, application, and requested permissions.
  3. Return to the dashboard. It checks for approval automatically and shows the connected account.
  4. For GitHub, use Manage repository access to install the ShipGremlins GitHub App on the repositories you want the crew to use. Account sign-in and repository installation are separate steps.
  5. In Projects, choose the source provider and a writable repository from the picker. Search or refresh if a newly authorized repository is missing.

Keep the original dashboard tab open while approving. Device codes expire; canceled, denied, or expired sign-in can be started again. A temporary provider error pauses polling and offers Retry status. Connecting source control does not start a job or change your app’s code.

Choose the repository your crew can actually use

The picker reads repositories from the connected provider rather than guessing their names. It shows the default branch and visibility after selection. Read-only repositories are unavailable for enrollment because Coding Gremlins need to publish work branches and draft PRs or MRs. An empty list can mean the GitHub App was not installed on that repository, the account lacks access, or the search is too narrow.

Manual tokens and self-hosted GitLab

If official sign-in is unavailable, open Advanced: use a personal access token under Source control. Save a source token there, then choose Enter a repository manually in Projects. GitLab accepts group/project and group/subgroup/project. For a self-hosted GitLab instance, enter its HTTPS origin, such as https://gitlab.example.com, without a project path, credentials, query, or fragment.

The official browser buttons connect to GitHub.com and GitLab.com. Self-hosted GitLab uses the advanced manual-token path. Its token should only be used with the server that issued it. The GitLab repository picker uses browser sign-in; a manually saved GitLab token does not automatically trigger discovery against GitLab.com.

Where source credentials live

Provider authorization is stored encrypted under .run/source-control/ in your configuration directory. Keep that folder and its encryption key together in private backups. Manual tokens stay in .env. Source credentials remain on your ShipGremlins server and are supplied to jobs when needed, with credential refresh coordinated around running work. A failed OAuth connection asks you to reconnect; it is not silently replaced by a personal token.

Use Disconnect to remove browser authorization from this instance. It keeps project configuration and any separately saved token. Provider-side app access can also be reviewed in your GitHub or GitLab account settings. See the source-control reference for permissions, storage, refresh behavior, and troubleshooting.

2. Connect your tools

The dashboard has separate Overview, Connections, Projects, Your gremlins, Activity, Usage, and Settings pages. Choose a project in the sidebar to see its next useful action and crew. Focused pages keep Environment, Review, Knowledge, Delivery, and Run limits separate. Open a PM for its brief, Learning, Features, Queue, Memory, and run history. Discovery lives under Learning. Browser Back, Forward, and direct links work normally.

Connections groups service cards by source control, AI and teamwork, hosting, product signals, and project access. Open a card for its setup steps, token creation link, and private credential form. Start with source control and Claude Code; connect other services when the chosen assignment needs them.

Different projects, different accounts

Linear and Vercel support multiple named connections. Open Add another account or workspace, give it a name, and authorize that account. The card's dropdown chooses which connection you are managing; it does not reassign your projects. Select each app's Linear connection and each Vercel environment's connection in project settings. A personal project and a client's project can use separate workspaces at the same time.

Your existing connection remains the default. A missing named connection blocks work rather than borrowing another account. Railway and Cloud Run targets can select their own named credentials, and repository-only apps need no hosting connection.

Read the repository's complete setup guide for commands, secret names, Docker options, and migration details.

A repository first. A browser when you need it.

Give your gremlins a test home

For an existing app, begin on the project home: let a Setup Gremlin inspect actual source files, then review and confirm the selected install and check commands before adopting a PM. If the repository branch changes, inspect it again before applying old suggestions. Confirmation preserves unselected settings and does not run commands or verify an environment. You can still write the PM brief yourself.

Open Environment when you need browser testing. The source analysis also recommends a test strategy; the PM’s first read-only Discovery can run without a test environment. A new idea shows its foundation build here first; environment analysis waits until application code exists.

Source investigation follows application entrypoints, imports, web assets and relevant test fixtures, with up to 80 source reads and 512 KiB of selected context. Open Reviewed files for selection reasons, excerpt line ranges and unread references. This is a bounded source investigation, not proof that every file was reviewed. Older saved reports use the earlier selection method; choose Analyze again after updating.

The analysis card shows connection status for this project's source provider and Claude; configured services offer Manage connections. If analysis fails, its message identifies the model or runtime problem without exposing private output. Use Retry analysis after addressing that cause. Any retained report is labeled as a previous suggestion, not the result of the failed attempt.

  1. Detect. Review the stack, inspected files and missing inputs. Analysis does not mean the application has been tested.
  2. Choose. Use an existing hosted staging URL or a saved Railway/Vercel/Cloud Run target. Or choose a disposable Docker app built from a repository Dockerfile or existing image, with optional fresh PostgreSQL and Redis.
  3. Test. Save named test inputs in Connections. The controller opens Chromium, checks any configured password test accounts, and captures a private screenshot. Docker test stacks are removed after the check.
  4. Ready. Choose Open project to return to your crew. Browser work can now use the tested environment. Each Docker-backed job starts its own application on the machine executing it.

If local setup files are missing, the gremlin can propose a Dockerfile, synthetic seed scripts and instructions. Review their contents, then create a draft setup PR or MR. Merge reviewed files yourself and test again. Vercel also offers an explicit reviewed preview-creation action; setup never auto-merges.

Test ShipGremlins in a disposable container

ShipGremlins includes a dashboard test fixture using the real UI and configuration handlers with clearly simulated integrations and runs. Choose Dockerfile examples/dashboard-test/Dockerfile, context ., port 3000, health path /fixture/health, and public access. It needs no hosted staging, real credentials or Docker socket. It exercises dashboard flows; real OAuth and worker execution need separate integration tests.

Each project and PM shows a Patrol plan with its test target and configured test-account names. Use Environment & accounts to change them. Run summaries separate worker completion from recorded browser calls, saved images and reported checks; select a card to open the underlying Activity or Evidence. Calls are attempts and images can be fixtures, so a finished run alone is not proof that the app was tested.

Keep your Railway pm-staging flow. Choose its existing target and retain your promotion branches and settings. A setup screenshot proves access, not an unmerged fix. Exact-candidate review and promotion evidence still apply. Managed Docker supports one app plus PostgreSQL/Redis; arbitrary Compose stacks and Railway environment creation are not included. Vercel preview creation is described below.

Onboarding, test accounts, Docker recipes, and current limits →

Verification starts in Repository only, so initial source inspection needs no hosted app or test account. New projects use managed promotion with pm-staging, staging, and main; finish the integration and browser setup before using that delivery loop. A library, CLI, or backend can explicitly choose the direct pull-request workflow and stay repository-only. Existing projects keep their chosen workflow.

Review the inspection’s suggested install, test, lint, typecheck, and build commands before confirming setup. You can also edit them in project settings. Suggested commands need your review; defaults are examples. Your worker image must provide the required language and tools; entering a Go or Rust command does not install its runtime. Repository mode reports repository evidence, not screenshots of an app it never visited.

To explore a web interface, select a Vercel, Railway, Google Cloud Run, or Docker or another host target. Give it a name and a preview or staging role. Browser verification chooses one named environment; production targets cannot be selected. Your draft PR base and deployed test branch are separate settings.

"workflow": { "kind": "pull-request", "baseBranch": "main" },
"verification": { "mode": "browser", "environment": "qa" },
"environments": {
  "qa": { "role": "staging", "kind": "url", "url": "https://qa.example.com" }
}

Edit an existing project

Use Edit settings beside its card to change commands, workflow, or its selected test environment. The sticky header identifies the project and repository, with shortcuts to project settings, Linear mappings, and product signals. The form preserves unrelated settings and other named environments. Changes clear the old verification stamp; run Verify connections again. A revision conflict keeps your draft instead of overwriting another process’s changes. Close and Escape offer to keep or discard unsaved edits.

For ShipGremlins itself, use npm ci to install, npm test to test, npm run lint to lint, and npm run typecheck to typecheck. Leave Build blank and choose Repository only. The worker needs Node.js 22.12 or newer.

Use Open full configuration to remove or rename environments, record production targets, or edit advanced sign-in and telemetry settings. Hosting credentials belong in Connections; project settings use IDs and credential variable names. The project and hosting reference includes complete examples and migration boundaries.

Give browser runs a test login

Environment first asks Does your app have a sign-in? Choose Yes, test signed-in flows for private product journeys. Create a dedicated test user in your app with the role you want exercised. Choosing a role name in ShipGremlins does not create that user or grant app permissions.

Source inspection can suggest a password login route and its browser controls. When a complete recipe is found, choose Use detected password login; you do not need to type CSS selectors. Reviewed suggestions remain available while you finish hosting setup, labeled with their limitations. Recheck them against the current app. An incomplete or unreviewed stale observation needs another inspection or explicit manual setup. Source detection never counts as a successful login.

Choose Save & add test credentials to save generated secret reference names and open Connections → Project access. Enter the actual email and password there, then return and run Test environment. Existing references can be reused. No credentials are put into PM briefs, tickets, or these public examples.

If detection cannot establish a recipe, supply the same-app login path and controls manually. The signed-in success selector must identify something available only after login, such as your account menu; a page heading or submit button is not enough. The browser must actually sign in with the saved account before scheduled browser PMs become ready.

The supported checker fills a username and password before submitting once. Email codes, magic links, MFA, external SSO, and multi-step sign-in flows do not fit that checker. The legacy Neon OTP recipe does not establish end-to-end browser support and is unavailable to Grumblin simulations. Keep sign-in coverage marked unverified until a supported test login has actually passed.

Test-account fields, secret references, and current login limits →

Connect Linear: an app team, a project per PM

In Connections, choose Connect Linear, authorize your workspace, and return to the same dashboard tab. Save or clear unfinished forms first. The connection works with a local dashboard or its private LAN address; keep the dashboard server running throughout authorization. The card shows the connected workspace and whether it needs reconnecting.

ShipGremlins requests read and write access as the authorizing user. Your workspace’s permissions and plan limits still apply. Team creation may require an administrator; use an existing team if your account cannot create one. The connection does not request broader admin access to bypass those restrictions.

Choose your app’s home for work

Connect Linear when an assignment needs proposals or coding. Adoption, a foundation build, or a PM run can prepare missing team and PM-project mappings using the app’s selected account. To reuse your existing organization, choose its team in Edit settings → Linear mappings before starting. Known mappings are preserved; connecting an account alone creates nothing.

You do not need to assemble every mapping by hand. With a saved connection selected, the PM prepares missing team/project mappings and required labels when it needs Linear. Existing mappings stay in place. Use Manage Linear mappings or Edit settings → Linear mappings to choose particular existing resources or repair an account choice. Changing accounts clears the draft team/project choices so you select resources from the right workspace.

Save Linear mappings repairs local configuration and its recovery journal together. It does not move or delete anything in Linear. Leaving a PM unmapped pauses it; valid mappings do not automatically enable paused PMs. Create missing Linear projects is also available as an explicit setup action. Connecting an account or opening the dashboard alone creates nothing.

Adopt another PM Gremlin

Each newly created Linear project gets a green 👾 icon and a complete PM brief: its mandate, source repository, ownership, schedule, work limit, evidence expectations, and first-patrol checklist. It explains how PM Gremlins propose work, Coding Gremlins implement approved tickets, and Done waits for production. Existing projects you choose to reuse keep their content and branding.

  1. Open your project from the sidebar. For a newly imported app, inspect the repository and confirm the selected setup suggestions, then choose Adopt a PM Gremlin.
  2. Describe what your gremlin should take care of, then choose Meet my gremlin. Or choose Write the brief myself.
  3. Meet the proposed gremlin and review its name and job. Open Review full brief for its product direction or Advanced settings for ownership, schedule, work limits, and Linear choices.
  4. Choose Adopt [name] to save it with automation paused. Connect optional project signals or skip them, then choose Explore the codebase to run Discovery, or Prepare first mission when setup is needed. Discovery needs source access, Claude Code, and a ready worker; Linear and a browser environment can wait. A fresh idea points to Build the foundation first.

Closing the dialog or pressing Escape keeps your unfinished draft during the same dashboard session.

New PMs start with automation paused. Adoption saves the brief and any chosen mapping; it starts no PM or coding job. Choose Explore the codebase explicitly for the first Discovery mission. Use Run now for later patrols while automation is paused. Coding Gremlins still require an open ticket approved with pm-approved.

Approve work for Coding Gremlins

For new managed projects, review and approve the epic in Proposals. The controller records the reviewed scope; the PM can then create and approve finite child tickets in its mapped Linear project. Children must reference that epic and stay inside its scope. Approving an individual child or applying an approval label to an epic does not substitute for the controller’s owner-approval receipt.

Start coding picks an eligible ticket on your runners, or enable automatic pickup with Activate ready crew. Work already running or awaiting PM QA is reused. Ordinary implementation, integration, and repair PRs do not require a separate human review in this workflow. Existing direct-PR and legacy ticket-policy projects retain their configured approval behavior.

What “Meet my gremlin” prepares

Describe the job or pick a suggestion from the source inspection, then choose Meet my gremlin. AI drafts a name and product brief around that goal. It covers ambition, outcome, users, expected capabilities, priorities, guardrails, non-goals, and measurement. Drafting uses current repository paths, existing ownership, and relevant saved source excerpts when available. Saved excerpts are labeled with their inspected commit; they are not a fresh full-source review.

AI drafting needs saved Claude credentials, repository access, and Docker on the dashboard server. Your retained crew suggestions let you adopt different responsibilities sequentially without repeating the initial scan. For a deeper investigation of source and tests, save the PM and run Discovery.

Your original goal stays the mandate. Use Review full brief and Advanced settings to adjust the draft before choosing Adopt [name]. Generating a draft does not save configuration, create Linear resources, enable automation, or queue a PM or coding job. If you edit the draft or switch projects while AI is working, a stale result will not overwrite your changes. Write the brief myself remains available.

Recover a partially finished setup

If Linear denies a request or a connection fails halfway, the local app or PM remains saved. Open its Linear mappings and retry creation after fixing access. ShipGremlins records intended IDs before requesting creation and reuses them on retry. To use different existing resources, explicitly save corrected mappings instead of creating the app again.

Keep the recovery journal at .run/linear/provisioning/ in your private backups. See the mapping and recovery reference for legacy teams, workspace changes, and restart behavior.

Connect Vercel and verify a real preview

Choose Connect Vercel in Connections and authorize the account or team and projects your crew needs. This is a Vercel integration with project and deployment access. It is not just an identity sign-in. If browser installation is unavailable, the advanced personal-token form remains available.

For manual setup, the card links to Vercel Tokens. Create a ShipGremlins token for your team or project, choose an expiration, then paste it into the personal-token form and save.

Open Project → Environment → Use hosted staging → Find my Vercel environment. Choose a saved account, find its projects, and select the project linked to your repository. Ready Preview deployments and existing custom staging environments appear with their branch, commit and status. Select a READY preview and use it: ShipGremlins saves the provider target, so you do not need to paste a test URL afterward. Each run resolves the current matching deployment and its URL. Then choose Test environment. Normal discovery needs no pasted project IDs and no AI call.

Your saved target follows the branch’s newest deployment on later runs. A failed or building deployment blocks the run instead of silently falling back to old code. Production deployments cannot be selected as previews. A separate test project using Vercel’s Production target can use the explicit URL option after you confirm it is a nonproduction app.

No test preview yet?

  1. Choose Create a test preview and review its branch, source commit, and Vercel project. The default branch is pm-staging; a missing branch can be created through your source connection.
  2. Configure test databases, storage and other services in Vercel’s Preview variables. Confirm they are safe for PM testing. Preview deployments do not automatically isolate your data.
  3. Choose Create preview. The dashboard follows the build and lets you use the environment once it is ready. This uses your Vercel build allowance and requires deployment write access.

Ask Setup Gremlin explains the discovered setup and your next step through a short conversation. This uses your saved Claude connection and Docker. The conversation cannot change settings or deploy by itself; reviewed dashboard actions perform those steps. Keep tokens and passwords in Connections.

Read-only Vercel access can discover environments. Creation may require reconnecting with additional permission or using the advanced personal-token connection. ShipGremlins does not create a new Vercel project, provision databases, copy production secrets, or invent test accounts. Full Vercel setup and recovery guide →

Choose Connect preview access in Environment to check Vercel’s protection and create or reuse a dedicated automation bypass through your saved connection. With unsaved environment changes, the button reads Save & connect preview access. ShipGremlins stores the credential privately; you do not copy tokens or invent secret names. Public previews need no new credential. Then choose Test environment to check browser access.

Vercel’s bypass works across that Vercel project’s deployments until revoked. Deployment protection stays enabled, and your app’s own login remains separate. If the connection lacks permission to manage protection, reconnect with that permission or use Advanced preview access to save a manually created bypass in Connections. Connecting an account alone creates no deployments, test accounts, or test data. Legacy vercel configuration remains supported; new projects use named environments.

Credential storage and disconnecting

Linear and Vercel OAuth state is encrypted locally under .run/oauth/linear/ and .run/oauth/vercel/. Back up each complete directory, including its separate encryption key, privately. Manual keys remain in .env. Saved credential values are never returned to the dashboard.

Named connections have separate encrypted state and keys under each provider's connections/ subdirectory. Saved OAuth takes precedence over a manual token. A revoked OAuth connection asks you to reconnect instead of silently changing accounts. Disconnect affects the selected saved connection; only the default connection can fall back to a separately saved manual token. It does not uninstall a shared provider integration. Active jobs may need to finish before disconnecting or refreshing a credential.

The controller uses Vercel credentials for preview lookup. Linear access is supplied to workers for proposals and approved work; refresh tokens and provider client secrets stay out of job payloads. Read the OAuth permissions, storage, and refresh reference for the exact credential lifecycle.

Connect Railway

Open the Railway card and follow its link to Railway Tokens. Create a ShipGremlins token for the workspace containing your apps, paste it into the card, and save. Choose Account/workspace as the token type in project settings. For one environment, create a Project Settings → Tokens credential in Railway and choose Project in ShipGremlins.

Save a Railway API token in its Connections card. This uses a manual token, not OAuth. Choose the narrowest account, workspace, or project access available. In project settings, select Railway and enter the project, environment, and web service IDs. Choose Project token only when your token was issued for that Railway project; account and workspace tokens use the default type.

The target defaults to the RAILWAY_TOKEN variable. You can name a different saved token for an environment. Set the deployed preview branch if it differs from your PR base. Discovery reads the existing service, deployment state, and URL; it does not create environments or deploy your code. Use an existing domain or a reachable direct URL when the service has no usable discovered URL.

Cloud Run, Docker, and other hosts

For Cloud Run, enter the Google Cloud project ID, region, and service name. Use Application Default Credentials on the controller, or paste service-account JSON in Connections and select its variable name, normally GCP_SERVICE_ACCOUNT_JSON. A blank key is not proof of a working machine identity; Verify connections checks actual access. Grant only the read permissions needed for that service.

The controller reads Cloud Run metadata and its URL. It does not provision a service, deploy a revision, or change IAM. Browser access to a private IAM-protected service is not injected by this release. Railway and Cloud Run account credentials remain on the controller, outside agent payloads.

For an app already running on Docker, a homelab, or a VPS, supply an existing HTTP(S) test URL reachable from the worker. To have ShipGremlins start the app itself, choose Docker on the project's Environment page. Managed app containers use private per-run networks, test-only inputs and cleanup; no host ports or Docker socket are exposed to the gremlin.

Inside a worker, localhost is the worker. Use a reachable LAN address or http://host.docker.internal:PORT for an app on the Docker host. The worker includes a host-gateway mapping. Check the app’s bind address and firewall; another container needs a published port or a shared network.

Provider settings that matter

Save credential values in Connections, then reference their names in project settings. Saved does not mean live access has been verified. Use Verify connections for each project after setup.

ConnectionPurposeWhat to configure
GitHub or GitLabSource, work branches, and draft PRs or MRs.Connect the official provider app and choose a writable repository. Manual tokens and a self-hosted GitLab HTTPS origin remain advanced options.
LinearScoped proposals and approved tickets.Select a saved account. The PM prepares missing team/project mappings and required labels; existing mappings stay in place.
VercelDeployment and preview checks.Select a READY preview from the saved account. The saved target resolves the current matching deployment and URL for each run. Choose Connect preview access to prepare a protected preview automatically, then test the environment.
RailwayOptional existing service and deployment discovery.Manual token, token type, project/environment/service IDs, and optional preview branch.
Cloud RunOptional service URL discovery.Project, region, service, and controller identity or service-account JSON. No browser IAM injection.
Direct URLA browser target on any reachable host.HTTP(S) preview or staging address reachable from Docker; no provider account required.
Claude CodeThe current PM and Coding Gremlin runtime.CLAUDE_CODE_OAUTH_TOKEN. Other AI runtimes are planned.
SlackCrew updates in one channel.Connect once for the workspace. Project overrides are optional.
SentryScoped errors and logs for PM investigations.Enable it for a project; set the host, organization, project, environment, and read token.
DatadogApplication logs for PM investigations.Choose a site, service, and environment; save API and application keys with log read access.
MixpanelSaved Insights reports for PMs.Choose the region and project, save service-account access, and assign a report to each PM.

GitHub and GitLab are source providers in this flow. Actions or GitLab CI runner registration is unnecessary. Hosting is optional; Vercel, Railway, and Cloud Run connectors discover existing resources, while direct URL targets support other hosts. Use isolated test accounts and data for browser work.

Manual tokens are saved in your configuration directory’s .env. Existing values are not sent back to the browser, and blank inputs keep them. Exported variables take precedence over saved manual values; an existing OAuth connection remains authoritative for that provider. The .env file is not encrypted, so keep it private and out of Git. Known credential values are redacted from retained output.

The Claude field accepts the token itself, copied terminal line wrapping, or a quoted CLAUDE_CODE_OAUTH_TOKEN assignment. Pasted text is never executed. If saving fails, the dashboard distinguishes token formatting from file permissions, read-only storage, or malformed .env content. Check permissions for the account running the controller on your server; existing credentials are preserved on failure.

3. Add your app

Choose GitHub or GitLab and select your app’s writable repository from the dashboard picker. Manual entry is available for token-based setups. There is no automation repository to create and no fork required. Let the Setup Gremlin inspect the source, review the suggested commands, and choose Confirm setup for the settings you selected. Adopt a PM, optionally connect project signals, then start its read-only Discovery. Edit settings remains available for commands, the PR base branch, and browser targets. Configure and test a browser environment when the chosen work needs one.

You can also initialize a GitHub project from the terminal:

gremlins setup init --project my-app --repo your-name/my-app

This command creates configuration offline. Continue inspection and PM adoption in the dashboard. Connect Linear when the PM needs to propose work; it prepares missing mappings from the selected saved account.

Configuration lives in ~/.shipgremlins unless you launch from an existing configured checkout or choose --home PATH. Existing project files are preserved. Configuration and installation folder paths are available in the dashboard.

Know your project files

The Configuration editor validates JSON and schema before saving. If another process changed the file, a conflict keeps your draft intact. Copy it, reload the current version, then reapply the intended changes. Saving does not commit or push a repository; the controller reads saved settings directly.

Use --home PATH consistently to select another configuration root. Otherwise ShipGremlins uses SHIPGREMLINS_HOME, an existing hub.json in your current directory or its parents, or ~/.shipgremlins. The dashboard shows configuration and installed-runtime paths. In a remote session, those paths belong to the server.

gremlins --home /path/to/my-gremlins setup
gremlins --home /path/to/my-gremlins setup status --json

Guided setup keeps the next step visible

The project tracks repository access, AI and worker readiness, source inspection, crew adoption, Linear setup, tested app access, and activation. Resolve the next missing step through its action. The activation action rechecks the current settings for every adopted PM and enables the crew only if all prerequisites pass. It cannot approve an epic, and a settings conflict requires a fresh review. Slack and product signals stay optional.

4. Create a local worker

In Your gremlins, choose Create local worker. ShipGremlins builds the Docker image and runs a real browser check before the worker becomes Ready. Each worker handles one job at a time on the dashboard’s host machine. Docker must be running there.

Pick a project and mapped PM mandate for Run now, or an open Linear ticket approved with pm-approved for a manual Coding run. Neither action turns on automation. Follow its actual output and screenshot artifacts in the dashboard. You can verify, repair, pause, or remove an idle worker. GitHub and GitLab hold your source and pull or merge requests; provider CI is not required to run these workers.

gremlins doctor my-app

Worker capacity and controls

A worker is execution capacity, not a PM identity. Many mandates can share one worker. Each slot runs one job at a time, and the local pool supports up to four workers. Create only the capacity your host and AI account can support.

Jobs have a 45-minute execution limit. A failure before a container launches gets one infrastructure retry; failed agent work is not automatically replayed. Recovery checks existing containers before deciding their state. Read the failed run’s output and evidence before requesting another implementation.

Choose the right gremlin

PM Gremlins investigate. Adopt one for a focused product responsibility, then choose Explore the codebase for its first Discovery mission. This learns the repository without Linear or a browser environment. Later, use Run now for a patrol that can propose improvements with evidence. Patrols check their prerequisites and can prepare missing Linear mappings and required verification. Automation can stay paused.

Coding Gremlins implement. Choose Start coding to find the next eligible ticket or enable automatic pickup. The worker rechecks approval and PM ownership, makes the scoped change, and runs configured checks. In managed projects, the controller handles the internal PR and the owning PM performs QA. The owner reviews the promotion batch. Direct-PR projects retain owner review of coding drafts.

Use the PM or Coding launch controls beside a project, or choose a crew in the workbench. Activity shows running and past jobs with visible tool calls, progress, summaries, check results, raw output, and screenshot artifacts. Production merging remains your decision.

Choose your gremlin’s job

Choose Adopt a PM Gremlin on the project. Tell it what to take care of and choose Meet my gremlin, or Write the brief myself. Review its name and proposed responsibility before adopting. The full brief and advanced settings are available separately; you do not need to fill every control to meet your first gremlin.

Start with one narrow product responsibility. Name the users, paths, behaviors, acceptance criteria, and boundaries the PM should investigate. Describe the product outcome you care about, not just a list of pages to click.

Example: the import PM
Own CSV import from upload through confirmation. Explore malformed rows, empty files, duplicate entries, large inputs, and mobile feedback. Use synthetic contacts only. A successful import explains which rows were accepted or rejected without losing valid data. Propose a ticket with reproducible input and browser evidence before implementation.

Open a project from the sidebar, then adopt or select a PM. Its Product brief can include ambition, users, a goal and measurement definition, expected capabilities, priorities, guardrails, and non-goals. These owner instructions are saved in areas.json, separate from learned memory. Editing a brief preserves its Linear mapping and automation state; conflicting saves are rejected instead of silently overwriting another browser’s changes.

Review ownership, shared touchpoints, the Linear mapping, and the area label such as pm:core. New PMs begin paused. Use Discovery to gather codebase context, then finish verification and review a Run now patrol before choosing the appropriate automation control.

First, let your PM learn the codebase

A Discovery run reads the actual checkout, source, and tests, then produces four documents for the PM’s workspace. It needs source access, the Claude Code connection, and a ready Docker worker. You can use it before Linear or hosting is configured.

DocumentWhat it captures
DiscoveryArchitecture, relevant source paths, test strategy, and what remains unknown.
FeaturesThe area’s existing capabilities and evidence for their status.
QueueRanked product opportunities and defects, with expected impact, confidence, and next steps.
MemoryUseful observations, blockers, owner questions, and what a later patrol should investigate.

The worker records the checked-out commit and run provenance. Valid documents become context for later patrols, which can refresh the learned notes. Incomplete or invalid new output preserves the last valid snapshot. Changes to the owner configuration mark existing knowledge stale; run discovery again to refresh it.

Learning does not grant approval. Discovery cannot file Linear tickets, publish code, change ownership, rewrite your brief, or enable automation. Repository observations are not live browser evidence. Regular patrols still need their configured connections and verification, and Coding Gremlins still need approved tickets.

Give the PM an outcome worth improving. Patrols start with previous coverage and unresolved questions, trace a concrete path end to end, and attempt a focused test. Passing a broad suite does not prove an untested security boundary. The PM saves sanitized evidence and explains what it actually checked; if access or time prevents meaningful investigation, its report must say so. There is no minimum ticket quota: a no-ticket result needs evidence, and an unsupported suspicion must not become a fabricated defect.

Learned documents live in .run/pm-knowledge inside the configuration directory and survive updates. Back them up with your projects. Read the full PM workflow on GitHub →

Run now, automate, or pause

ActionWhat it changes
Activate ready crewRechecks every adopted PM’s prerequisites, then enables scheduled patrols and eligible coding together. It does not approve an epic.
Run nowQueues one eligible PM patrol, including while automation is paused. Managed patrols handle their pending QA first. It does not enable a schedule.
Start codingQueues one approved ticket with finite acceptance criteria, the matching area label, and the PM’s Linear project.
Look for new improvementsEnables scheduled PM patrols independently of coding pickup.
Automatically build approved workEnables pickup of eligible approved tickets independently of patrols.
Turn either control offStops new work for that automation. Existing jobs are not canceled; use Activity to cancel a run.
Pause workerStops that Docker slot accepting work; it does not change any PM’s automation setting.

Schedules and approved tickets

Schedules use five-field cron in UTC. For example, 0 13 * * 1-5 means 13:00 UTC on weekdays. The controller must remain running for scheduled and queued work. Each scheduled slot or ticket attempt has an idempotency key to avoid duplicate execution.

In the managed policy, PMs propose epics with pm-epic and pm-proposal. Owner approval is recorded by the controller. The PM may mark in-scope child issues pm-approved, with their native Linear parent relationship, area label, and project mapping. Admission checks the parent receipt and current scope again before coding. Explicit owner holds and review-only mandates remain in force.

WIP limits count active implementation and delivery work, including changes waiting for deployment or PM QA. A finished worker run is an intermediate state. Do not mark a ticket Done to create capacity; Done still requires confirmed production inclusion.

Your project control room

Choose an app in the sidebar. Its Your next change page puts reviewable changes, blockers, and active missions first. Proposals holds owner decisions; Changes collects coding results and links to advanced staged delivery. Your crew keeps PMs, Grumblins, and shared knowledge; Settings contains environment and run limits.

Discovery can suggest commands and ownership based on manifests and tests it actually read. In the PM’s Learning page, a Setup suggestions ready card opens Review suggested setup. Review the exact commands and supporting files there, then apply commands or ownership explicitly. Your worker must already have the required toolchain. Suggestions never enable a schedule or execute themselves.

One place for the next decision

The workspace Review inbox collects setup blockers, stale discoveries, failed runs, and owner decisions. For managed projects, your decisions are the proposed epics and the final promotion batches. Project Proposals fetches current Linear scope; read the outcome, acceptance criteria, and exclusions before approving an epic.

Approval rechecks the epic and refuses changed scope or mapping. The PM decomposes an approved epic into independently testable child issues; you do not approve each coding or integration PR. Each PM’s verified work accumulates toward its promotion threshold, 10 tickets by default, with a project default and optional per-PM override. A smaller prerequisite batch can unblock tested work in another PM’s area; it keeps its owner, evidence checks, and human promotion review. Changing direction or expanding the epic needs new approval. Production merge remains separate.

Several PMs. One project memory.

Open product knowledge under Your crew to add concise owner decisions. PMs and Coding Gremlins receive those decisions alongside current sibling summaries and shared ownership paths. An older discovery is marked stale when its owner settings change and is excluded from future context until refreshed.

Owner decisions remain separate from learned observations. Gremlins cannot rewrite your decisions, grant themselves approval, or borrow another project’s knowledge. Coding jobs with overlapping ownership wait for the current run, reducing competing edits while independent projects can keep moving.

Keep the crew within bounds

Set project concurrency, daily runs, daily agent runtime, and a per-job duration under Run limits. Daily budgets use UTC. Runtime is reserved before launch, and queued work waits when the budget is used. This measures PM/coding job containers; independent post-run browser replay and promotion checks have separate bounds. It is not total machine compute or a dollar bill.

Use Cancel run in Activity to stop one job. Cancellation requested and cancellation confirmed are different states, and the job’s existing output is retained. Pausing a PM stops future automatic work; pausing a worker lets its current work drain.

Confirmed startup infrastructure failures have bounded retries with backoff. An uncertain launch or possibly completed publication is held for review instead of blindly repeated. Read the operations guide →

Put a worker on another machine

In Your gremlins, enroll a remote worker and select which projects it can run. Copy the one-time command to that machine. The worker connects outbound to your controller, builds its Docker image, and proves browser readiness before taking work. No source or Claude token goes in the command.

gremlins worker --controller https://gremlins.example.com --enrollment-code ONE_TIME_CODE

Keep the process running; later starts use the same command without the enrollment code. A Linux cloud VM or a Windows/macOS Docker Desktop host can run it. Jobs run in Linux containers; native iOS simulation is not supported yet. Local and remote workers share four execution slots.

For an existing HTTPS reverse proxy, set SHIPGREMLINS_DASHBOARD_URL to the exact credential-free HTTPS origin on the controller. A private homelab can use the printed --lan URL with the worker’s explicit --allow-insecure-lan option. This does not add encryption. Never copy a dashboard #session URL into a worker command. Enrollment, networking and service setup →

Revoke access from the dashboard when a machine should stop receiving work. Active remote jobs use expiring leases and stop if the worker cannot renew its connection. A lost connection never causes a possibly completed coding run to be blindly repeated.

See the complete workflow diagrams: setup, epic approval, coding, QA, recovery, and per-PM promotions →

Activity and persistent run history

Open a run with View activity. Use Back to activity or press Escape to return to the run list. Closing this view does not stop a running job.

Open a recent run or View activity for a focused viewer with Summary, Activity, Output, and Artifacts tabs. Live events, raw output, and saved history load independently. Refreshes preserve your selected tab and reading position; a slow source shows a loading or partial-output message while available activity stays visible. Artifacts appear after the job finishes and their contents are sanitized. Back to activity, Escape, or leaving Activity closes the viewer without stopping the job. Run links can be bookmarked. A finished run means its process completed; inspect the summary and evidence to see which tests actually ran.

Open Activity to filter Running or Past jobs and select a project. Each run can show visible tool calls, progress, summaries, checks, raw output, and screenshots. These are operational actions and results, not a model’s private reasoning.

Local PostgreSQL stores run history, visible activity, logs, and artifacts. The managed history service is prepared with worker setup and binds its published port to loopback. Data lives in Docker storage, independently of a dashboard tab or individual worker. Load earlier activity from the dashboard when needed.

If history is unavailable, the dashboard reports it instead of presenting missing data as a clean run. Check the server and retain its database configuration and volume. A screenshot proves a particular browser observation; it does not establish that every acceptance criterion passed.

One Slack connection for your workspace

You do not need Slack for every project. Connect once and all projects use that channel. Slack is optional; jobs still run without it. Per-project webhook overrides are tucked into an advanced section for the few projects that need a different channel.

In Connections, open the Slack card and choose Add to Slack. First confirm the dashboard address you are connecting, then choose a Slack workspace and channel. The browser returns to your dashboard when authorization finishes.

One-click installation depends on the hosted Slack connection service being configured and available. If the dashboard reports it is unavailable, use Advanced: use an incoming webhook with a webhook you manage. Its value stays on your server and is never returned to the browser.

The same flow works from a homelab dashboard opened through gremlins setup --lan --port 4311. Keep that private session in the same browser tab during authorization. Slack updates do not mark a ticket Done or authorize a production merge.

Give PMs access to their project's signals

After adoption, the welcome step offers optional Sentry, Datadog, and Mixpanel setup for this project. Connect the services you use or skip the step and begin Discovery. You can return through the project’s Product signals settings. The first read-only Discovery does not query telemetry; later PM investigations use the selected scopes.

Connect Sentry logs and error events, Datadog logs, and Mixpanel analytics. PMs use this evidence alongside their browser observations to investigate failures and understand product usage.

Each provider has a visible card in Connections. Choose a project, open its settings, enable the provider and fill in its scope. Save, then enter the credentials in that provider’s project access fields. The same scope forms live under Projects → Edit settings. Your app must already send data to the providers; ShipGremlins does not install an SDK.

For Mixpanel, use Choose a saved report for each PM in its card. Select the project, enter the numeric saved Insights report IDs, and save. New PMs can set a report during creation. At least one PM needs a report for verification. Unrelated PM settings are preserved and conflicting edits are rejected.

gremlins logs --project my-app --hours 24 --limit 25
gremlins metric --project my-app --area core
gremlins doctor my-app

Logs are bounded samples from the configured project or service and environment. Mixpanel preserves the saved report's dates and breakdowns. Missing access is reported as unavailable, never as zero errors or zero activity. Use project-limited provider credentials.

Follow the project telemetry guide for configuration examples, regions, permissions, redaction limits and live connection checks. Adapters have automated tests; validate your own accounts before enabling scheduled PMs.

5. Match verification to the project

Repository-only projects verify configured source and job prerequisites and run their selected commands. Browser projects also resolve the chosen preview or staging target. Hosting discovery uses read access and does not provision your application. Worker readiness still uses its own browser check; that is separate from proving your app works.

The managed delivery loop

New projects use three distinct branches: integration (pm-staging), staging, and production. Choose a Vercel or Railway test target that reports the actual ready deployment ID, branch, and full commit SHA, then pass its current access check before activating promotion coding. A fixed URL, Docker target, or source-only configuration cannot establish that deployment evidence. Source investigations remain available while setup is unfinished. Existing projects keep their chosen policy; an explicit direct-PR workflow supports repository-only work and leaves implementation PR review to the owner.

  1. Approve the epic. The owner approves a finite outcome and its boundaries in ShipGremlins. PMs turn that scope into testable Linear child tickets.
  2. Implement and integrate. Coding Gremlins work on eligible tickets. The controller checks the published revision and merges internal coding, sync, and repair PRs into pm-staging when their gates pass. These PRs do not become owner review tasks.
  3. Test each change. The owning PM’s eligible patrol performs queued QA first on the exact ready integration deployment. It checks the individual acceptance criteria; a separate browser replay records trusted evidence.
  4. Return failed work. A genuine failed acceptance check adds feedback to Linear and returns the ticket to coding within bounded retries. Inaccessible environments and uncertain evidence remain blocked; they are not treated as a product pass or a new feature ticket.
  5. Build the PM’s batch. At the configured threshold—10 verified tickets by default—the controller selectively assembles that PM’s passing changes on the current staging base and checks the result. Other PMs’ work, failed changes, and unrelated integration commits stay out.
  6. Review once at staging. The owner reviews the promotion PR and its individual QA evidence, then decides whether to merge. Releasing staging to production remains the owner’s separate decision.

The controller also reconciles staging back into pm-staging while it is running. Pending checks, conflicts, or a stale deployment keep dependent work waiting. Bounded repair can resolve sync problems without asking you to manage an internal PR; branch protections still apply.

Ordinary PM-tested promotion does not need a separately hosted candidate. If you configure candidate verification, that additional gate must pass. For Railway, use a separate nonproduction candidate service; the fixed integration service cannot prove a different cherry-picked candidate. ShipGremlins does not provision paid Railway hosting or upload GitLab source automatically. Delivery and candidate setup reference →

A healthy check must match the current code revision. The controller holds ordinary work when integration health is unknown, pending, or failed. A bounded recovery lane can repair that branch.

Promotion needs trusted, revision-specific PM evidence and passing checks on the assembled candidate. If separate candidate verification is configured, its matching evidence is required too. A prose-only “verified” comment cannot authorize promotion.

Follow the verification workflow when upgrading an existing installation.

6. Keep Done honest

For new managed projects, the controller follows its recorded child deliveries through their merged promotion batches and the staging-to-production release. When production inclusion and the team’s completed Linear state are unambiguous, it reconciles completion automatically. A successful job, integration merge, or staging promotion alone is not Done. Uncertain evidence stays blocked.

Legacy promotion projects retain their explicit production declaration: select every required delivery, choose the staging-to-production PR and completed Linear state, then confirm the scope. Existing direct-PR projects retain their configured lifecycle. The owner still decides when to release production.

Implementation, QA, and staging are intermediate milestones. Use the tickets audit to inspect production inclusion; reconciliation requires a reviewed manifest and an explicit apply option. Uncertain historical mappings remain blocked.

gremlins tickets audit --project my-app
gremlins tickets reconcile --project my-app --manifest release-manifest.json

The second command previews changes by default. Read the Linear lifecycle contract before applying a reconciliation. Also check native Linear branch automations so integration merges do not close tickets early.

Keep your crew up to date

An update banner appears on every dashboard page when a release is available. Use Update now there, or open Settings → Updates. The banner shows installation and restart status; the dashboard checks periodically while visible. Updates only install when you choose to install them. Installing an update preserves your projects, mandates, and saved credentials; restart the dashboard to use the staged runtime.

gremlins update --check
gremlins update

How updates are applied

The updater selects an official commit with passing release CI, stages it in a separate per-user runtime directory, and validates it before selecting it for future launches. It preserves project files and credentials. Restart the dashboard to load the new runtime; running Docker jobs continue. The previous runtime remains available for rollback:

gremlins update --rollback

If an older installation has no update command, stop that dashboard once, repeat the global Git-URL install command, and reopen setup. On Windows, stop the processes using that installation before manually reinstalling to avoid a locked binary.

Back up the crew’s memory

Back up the configuration directory shown in the dashboard, including project JSON, mandates, memory, connection files, queue state, Slack connection state, the Linear provisioning journal, and encrypted source-control and OAuth folders with their matching keys. Treat that backup as secret-bearing. Keep a separate, consistent backup of PostgreSQL and its managed Docker volume; project JSON alone does not preserve Activity history.

Use a database-aware PostgreSQL backup or a consistent volume snapshot according to your host’s backup process. Keep connection configuration with the matching database backup. Test restoration, and retain completed job output volumes while diagnosing failures.

A runtime rollback changes executable code; it does not restore configuration, database history, or your app repository. Do not delete Docker volumes or reset corrupt queue files as a routine repair. Preserve the evidence and inspect the reported error first.

RETIRE A GREMLIN

Delete, disconnect & restore.

Open a project from the sidebar and choose Delete project, or open a PM and choose Delete PM. Review the impact and type the exact identifier shown in the confirmation. Queued, running, and unresolved delivery work must finish or be canceled first. You can remove the last PM and leave the project ready for a new crew.

Settings keeps your deleted projects and PMs with a Restore action. Restored PMs start paused, and the project needs verification again before automation resumes. You can create a fresh project or PM with the same name after deleting the old one. Its internal identity, learned memory, and delivery ownership start fresh; the old recovery copy and run history remain intact. A replacement project gets separate default credential names and requires a new remote-worker enrollment. Shared provider connections remain available. A new PM gets a new Linear project when provisioning is selected, unless you explicitly choose an existing one. Restore requires the name to be free. Recovery copies live on your server under .run/deleted/.

Connections offers Clear saved token for manual credentials and Remove saved account for unused named Linear or Vercel accounts. Change project references before removing a saved account. Disconnect removes OAuth authorization while keeping the account entry available for reconnection. Exported environment variables remain until you remove them from your shell or service and restart.

Your external resources and history stay intact. These actions remove local configuration; they do not delete Git repositories, Linear teams or tickets, hosted apps, or past run activity. Review shared credentials separately. Full removal and recovery reference →

When a gremlin needs a hand

The global command is not recognized

Reopen the terminal. Run npm config get prefix; that directory on Windows, or its bin subdirectory on macOS/Linux, must be on PATH. Reinstall from the complete Git URL if installation did not finish. The public command is gremlins; older aliases remain compatible.

Windows reports EPERM or a missing runtime

Stop this installation’s dashboard or watch process, then finish the global reinstall. An active process may hold esbuild.exe open. Leave unrelated Node processes alone. Source contributors can repair their checkout with npm ci; a normal global installation is used through gremlins.

Docker is unavailable or a worker will not become Ready

Start Docker Desktop or Engine with Linux containers on the dashboard host. Check docker info there, then Refresh in Runners. Let the initial image build finish. Inspect browser verification output, fix image/network/engine access, then use Repair. Ready requires matching browser evidence.

A project cannot run

Follow the selected action’s setup checklist: connect source control and Claude Code, then create or resume a ready worker. Discovery can start without Linear or hosting. Patrols need Linear and project verification; browser patrols also require a passed check of the current environment and app login choice. Coding needs a finite open ticket in the PM’s Linear project with the area and approval labels. Managed child work also needs a current controller-approved parent epic. Existing work, dependencies, and WIP limits can prevent duplicate or premature runs.

Linear or Vercel needs reconnecting

Refresh the provider’s card and check workspace or installation access. Save unfinished form entries before authorizing again. If authorization expires, restart it from that card. Use the advanced token form when browser setup is unavailable. A saved but revoked OAuth connection must be reconnected or explicitly disconnected before a manual token takes over.

My app saved, but its Linear team or PM project did not

Keep the saved app or PM and use Retry Linear setup. Check the authorizing user’s permission to create teams and projects, workspace limits, and the selected workspace. Choose an existing team before starting a new creation when needed. Preserve the provisioning journal; deleting it can lose the IDs needed for a safe retry.

A dashboard session expires or will not open remotely

Use gremlins status for the background controller’s current private link, or reopen foreground setup. From another device, use the printed LAN address and session fragment rather than its own localhost. Check the controller is running and the private-network firewall permits the chosen port.

A configuration save conflicts

Your draft is kept when the server file changed. Copy it, reload the latest version, and apply your intended edits there. Invalid JSON or schema errors appear before a save can replace the file.

Slack or Activity is unavailable

Refresh Slack status; save pending edits before reconnecting. Start canceled or expired authorization again from Add to Slack, or use the webhook option independently. For Activity, check the local history service and keep its configuration and data volumes. Missing history is not proof of success.

For deeper detail, use the setup reference, worker reference, project reference, or report an issue with redacted output and reproduction steps.

Know the alpha boundaries

Claude Code is the current AI runtime. Additional model runtimes, broader hosting automation, and automated fixture cleanup are planned. CSV and PNG upload fixtures are available through the gremlins fixture command. Existing GitHub Actions and GCP runner paths remain advanced compatibility options; GCP still needs live certification. The current release has focused automated tests; it is not a guarantee that every application or provider configuration has been certified.

Start with one PM, review its evidence, and expand once the workflow earns your trust. Follow the implementation roadmap or report an issue.