osprey

Getting started

This page explains how to build Osprey 0.1.0 and complete a first interactive task from the audited source commit.

This page documents source commit 01dabf2fedd1826362162ead9757232e89d9bfa5. The package metadata at that commit reports version 0.1.0.

The local v1.1 tag identifies separate history. The tag is not an ancestor of the audited commit. The audited commit has no exact version tag.

The release workflow publishes assets and install.sh to existential-birds/osprey-public. That public installer and release endpoint were not live during the audit. Do not use the public installer for this target. You need access to the private Osprey source repository.

Supported build platforms

The release workflow defines four build targets.

Operating system Architecture Rust target
macOS Apple Silicon aarch64-apple-darwin
macOS Intel x86_64-apple-darwin
Linux AArch64 aarch64-unknown-linux-musl
Linux x86-64 x86_64-unknown-linux-musl

The Linux workflow creates static musl builds. The source does not define a minimum supported macOS version.

Prerequisites

Install these programs before you build Osprey:

  • Git
  • Rustup and Cargo
  • Make
  • Bash
  • Python 3

The repository pins Rust 1.97.1 in rust-toolchain.toml. The package metadata declares Rust 1.92 as its minimum version. Use the pinned Rust 1.97.1 toolchain for this source target.

Osprey uses SQLite by default. SQLite requires no separate server. PostgreSQL is an optional storage backend for shared installations.

Verify the source target

The following commands only read repository state. Set REPOSITORY_ROOT to the existing private checkout.

REPOSITORY_ROOT="$HOME/src/osprey"

SOURCE_COMMIT="01dabf2fedd1826362162ead9757232e89d9bfa5"



cd "$REPOSITORY_ROOT" || exit 1

if ! test "$(git rev-parse HEAD)" = "$SOURCE_COMMIT"; then

  printf '%s\n' "The checkout is not at the documented source commit." >&2

  exit 1

fi

git status --short

Stop if the commit check fails. Do not combine these instructions with commands from v1.1.

Prepare the source checkout

make setup writes core/.env when the file is absent. The command also installs development tools into the Cargo environment. The command can download Rust tools. The command can also add a musl target.

cd "$REPOSITORY_ROOT" || exit 1

make setup

The generated core/.env selects the Uniform Resource Locator (URL) for the development PostgreSQL database. The installed application still uses SQLite when no database setting exists.

If you only need the application binaries, you can omit make setup. The next build and install commands still require the pinned Rust toolchain.

Build and install

make build writes build artifacts under core/target/.

cd "$REPOSITORY_ROOT" || exit 1

make build

make install writes two binaries under $HOME/.cargo/bin. The binaries are osprey and the operational agent-runner sidecar.

cd "$REPOSITORY_ROOT" || exit 1

make install

Add the Cargo binary directory to PATH when your shell does not find osprey. The next command changes only the current shell environment.

export PATH="$HOME/.cargo/bin:$PATH"

osprey --version

The expected package output is osprey 0.1.0.

Configure a provider key

Osprey reads provider application programming interface (API) keys only from environment variables. The configuration file never stores provider keys.

Choose one key variable:

  • OSPREY_ANTHROPIC_API_KEY
  • OSPREY_OPENAI_API_KEY
  • OSPREY_OPENROUTER_API_KEY
  • OSPREY_NOUS_API_KEY
  • OSPREY_ZAI_API_KEY

The next commands read a key from the terminal without echo. The commands set the key only in the current shell environment.

printf 'OpenRouter API key: '

IFS= read -r -s PROVIDER_API_KEY

printf '\n'

export OSPREY_OPENROUTER_API_KEY="$PROVIDER_API_KEY"

unset PROVIDER_API_KEY

Use the matching environment variable when you select another provider.

Run setup

osprey setup can read the remote model catalog. The command writes $OSPREY_HOME/config.toml with mode 0600 on Unix. OSPREY_HOME defaults to $HOME/.osprey.

The wizard prompts for a storage backend and a model. The wizard detects provider keys from the current environment. The wizard does not prompt for an API key.

osprey setup

Select SQLite for the default local configuration. The default database path is $OSPREY_HOME/sessions.db.

The wizard saves configuration after a failed database test. If the test fails, correct database_url in $OSPREY_HOME/config.toml. Then run osprey setup again.

Complete a first task

Bare osprey starts the terminal user interface (TUI). The launch writes hourly logs under $OSPREY_HOME/logs. The launch also creates a session in the configured database.

Start Osprey from a workspace that the agent can inspect.

cd "$REPOSITORY_ROOT" || exit 1

osprey

Enter this read-only first task:

Inspect README.md and summarize the build prerequisites. Do not edit files.

Osprey streams the provider response into the TUI. The TUI asks for approval before a requesting tool runs. The session remains available after Osprey exits.

Diagnose startup failures

If cargo is missing, install Rustup. Then reopen the shell. If the version differs from 0.1.0, verify the audited commit. Then reinstall Osprey. If no provider key exists, the TUI starts with provider guidance. Model requests fail until the current environment contains a valid provider key.

If project configuration fails to parse, fix the nearest .osprey/config.toml. Project configuration errors stop the launch. Global configuration errors produce a warning and load default values.

Remove the source installation

make uninstall removes the two Cargo-installed packages from the Cargo binary directory. The command does not remove configuration, sessions, logs, or source files.

cd "$REPOSITORY_ROOT" || exit 1

make uninstall

Back to Osprey