Install

Install Otter.

One command on macOS, one package on Linux. Both install two binaries — otter, the client, and otterd, the runtime.

  • macOS · Homebrew
  • linux/amd64
  • linux/arm64
  • darwin/amd64
  • darwin/arm64
  • Python 3

Get it

Pick the one that matches your platform. There is nothing to sign up for, and no installer to review.

macOS

A Homebrew cask from a tap. This is the whole install, and the same command upgrades it later.

Homebrew
brew install tkoizumi/tap/otter

Linux

A .deb per architecture. Set VERSION to the release you want — the filenames carry the version, so there is no unversioned URL to bookmark.

Ubuntu / Debian
VERSION=0.5.3   # or any tag from the releases page
ARCH=amd64      # amd64 or arm64

curl -LO "https://github.com/tkoizumi/otter/releases/download/v${VERSION}/otter_${VERSION}_linux_${ARCH}.deb"
sudo apt install "./otter_${VERSION}_linux_${ARCH}.deb"

Tarball

Both binaries in one archive, for a host where you would rather place them yourself. The archive name is a published interface.

manual install
VERSION=0.5.3
OS=linux        # linux or darwin
ARCH=amd64      # amd64 or arm64

curl -LO "https://github.com/tkoizumi/otter/releases/download/v${VERSION}/otter_${VERSION}_${OS}_${ARCH}.tar.gz"
tar -xzf "otter_${VERSION}_${OS}_${ARCH}.tar.gz"
sudo install -m 0755 otter otterd /usr/local/bin/

From source

With Go 1.22 or newer. Useful if you want to read the code you are running, or build for a platform we do not publish.

go install
go install github.com/tkoizumi/otter/cmd/otter@latest
go install github.com/tkoizumi/otter/cmd/otterd@latest

Installing by hand after using a package? Remove the hand-placed binaries from ~/.local/bin. A directory earlier in PATH wins, and otter version would then disagree with dpkg -l otter.

Verify

Check what you installed.

Both binaries report their version, and the runtime can print the contract it implements before you commit to it.

otter --json version is the machine-readable form: schema, contract, SDK and manifest versions in one object. A client uses it to establish what it is talking to before it holds a credential.

verify
otter version
otterd --version
otter --json version
output
{
  "schema_version": 1,
  "contract_version": 3,
  "product_version": "0.5.3",
  "manifest_schema": 1,
  "sdk_version": "0.1.0",
  "supported_platforms": ["linux/amd64", "linux/arm64", "darwin/amd64", "darwin/arm64"]
}

First job

Scaffold, release, run.

You do not need a project to start. This writes a workspace with one working job, a manifest, a pure-logic module and a test.

  1. Install and scaffold

    One command each, and you have something runnable.

  2. Validate and release

    Check the manifest without a daemon, then activate an immutable snapshot.

  3. Start and run

    The runtime picks a free loopback port and records where it listens.

  4. Read the state back

    Then stop the runtime. Nothing is left running that you did not ask for.

five minutes
otter init my-project
cd my-project

otter validate my-project
otter release my-project

otter start --detach
otter run my-project
otter state get my-project count

otter stop

otter start loads otter.env and otter.daemon.env if they exist, and records where it listens in .otter/serve/, so every later command finds the runtime on its own.

Requirements

What the host needs.

  Requirement Notes
Operating system Linux or macOS amd64 and arm64. Windows is not published.
Python Python 3 on the host Unless a job sets python.mode: managed, which prepares its own interpreter and locks dependencies.
Disk A data directory you choose Holds otter.db, the extracted SDK and release snapshots. Defaults to ./tmp, or /var/lib/otter in a service install.
Network None required The daemon binds loopback by default. Binding elsewhere requires an API token.
Memory Budget for the daemon plus your runs Roughly 256 MiB for otterd, plus the peak RSS of each concurrent run.

Upgrading

Same command, newer version.

Releases publish otter and otterd together from one archive. The binary pair is the unit — do not mix versions.

Every job must be released once after upgrading: the release digest format is versioned, and a deploy prunes inactive snapshots while always keeping the previous release as the rollback target.

upgrade
# macOS
brew upgrade otter

# Linux — download the new .deb and install over the old one
sudo apt install "./otter_${VERSION}_linux_${ARCH}.deb"

# then re-release each job once
otter release --all

Without installing

Other ways to run it.

Remote host

Deploy from your machine

otter deploy --host user@host cross-compiles locally, pushes the binaries, creates an unprivileged service account and installs the systemd unit. Nothing needs to be installed on the target first except the SSH access you already have.

Otter Cloud · alpha

Skip the host entirely

otter login then otter deploy --cloud promotes a release you already built and validated to a pooled tenant we operate. Alpha access is invite-based.

Every release, including the notes for the one you are installing, is on the releases page. The compatibility policy says what counts as a change to a frozen interface.

Installed. Now write a job.

The quickstart walks from an empty directory to a released, scheduled job.