#Configuration

#HTTP host and port

Set the listen address and port with environment variables. Shipplane Lite reads them at startup:

PORT=8080 HTTP_HOST=127.0.0.1 shipplane-lite

#Config file

On startup, Shipplane Lite looks for a config file matching:

$XDG_CONFIG_HOME/shipplane/lite.config.{ts,mjs,js,cjs}

If XDG_CONFIG_HOME is unset, it falls back to ~/.config/shipplane/. The first matching file (checked in the order .ts, .mjs, .js, .cjs) is loaded and merged over the defaults; the rest are ignored.

The file must default-export an object with this shape:

interface AppConfig {
  http: {
    addr: string;
    port: number;
  };
  workflows?: WorkflowDefinition[];
  registry?: TaskRegistry;
}

registry adds one TaskRegistry, built with @shipplane/core's createTaskRegistry(), to the two built-in task types. See Custom task types.

#TypeScript example

Each workflows entry is plain WorkflowDefinition JSON. Build entries with @shipplane/core's workflow() builder to get type checking and autocomplete. Install core in the config directory:

cd ~/.config/shipplane
npm install @shipplane/core

~/.config/shipplane/lite.config.ts:

import { workflow } from "@shipplane/core";

const deploy = workflow("deploy").task("install", {
  type: "@shipplane/local_cmd",
  params: { cmd: "echo hi" },
});

export default {
  http: { addr: "0.0.0.0", port: 4000 },
  workflows: [deploy.toJSON()],
};

The config loader runs your .ts file with Node's built-in TypeScript support. Because no bundler resolves imports, relative imports need explicit extensions when you split the config across files. Use import { deploy } from "./workflows/deploy.ts", not "./workflows/deploy".

#Workflow seeding

On every startup, Shipplane Lite inserts or updates the workflows in your config file, matching them by workflow id. This lets you keep workflow definitions in version-controlled config instead of creating them in the editor UI.

Seeding runs unless disabled — see --no-sync below.

#Removing a workflow

The config file owns the workflows it seeds. Rename or delete a workflow id there and the old one is deleted from the database on the next startup, along with its run history.

Four things are never deleted by seeding:

• Workflows created in the editor UI or through the HTTP API.
• A workflow that is currently running.
• Anything at all, when --no-sync is set.
• Anything at all, when the config file is missing or defines no workflows. Lite cannot tell an intentionally empty config from an unreadable one, so it leaves the database alone. Delete those workflows in the UI instead.

#Workflow limit

Shipplane Lite supports up to 10 workflows, including seeded ones. Re-seeding an existing id updates it without adding another workflow.

A config that seeds past the limit stops the server from starting, rather than skipping the extra workflow. Through the UI or HTTP API the same limit returns an error and the server keeps running.

#CLI flags

shipplane-lite serve [--no-sync]
shipplane-lite [--version]

The run, ls, logs, and registry subcommands act as clients of a running server instead of starting one. They read http.addr and http.port from the same config file. See the CLI.