Skip to content

Getting started

This guide takes you from installation to a first URSA conversation, then shows the terminal interface and browser dashboard. OpenAI models work without a config file; configuration is only needed when you want to change a default or use a different endpoint.

Install URSA

URSA requires Python 3.11 or newer. The uv tool installation is recommended:

Install uv if needed, then install URSA and the dashboard in an isolated tool environment:

uv tool install --python 3.13 'ursa-ai[dashboard]'

Update URSA with: ursa self update or uv tool upgrade ursa-ai

Use this option when you already manage Python virtual environments:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 'ursa-ai[dashboard]'

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install 'ursa-ai[dashboard]'

conda create -y -n ursa-env python=3.13
conda activate ursa-env
python -m pip install 'ursa-ai[dashboard]'

Verify both applications:

ursa --help
ursa-dashboard --help

Start with the built-in OpenAI configuration

Set your OpenAI API key and launch URSA:

export OPENAI_API_KEY="..."
ursa

$env:OPENAI_API_KEY = "..."
ursa

That is a complete working setup. The built-in openai inference provider already supplies the model and OpenAI base URL, so an OpenAI-only config file is unnecessary.

Choose workspaces deliberately

The execution agent can write files and run commands. Start URSA in a disposable exercise directory, or pass --workspace with a directory you are comfortable modifying.

Optional: customize your user configuration

Use a user config for defaults that should follow you across projects. Do not copy the same config.yaml into every project.

Platform User configuration path
macOS ~/Library/Application Support/ursa/config.yaml
Linux ~/.config/ursa/config.yaml
Windows %APPDATA%/ursa/config.yaml

For example, this changes only the embedding model and leaves the built-in OpenAI chat configuration intact:

emb_model:
  model: openai:text-embedding-3-large

Inspect the merged user configuration with:

ursa --print-config=user,resolved

See Configuration for other providers and precedence rules.

Learn the TUI

Run ursa. The welcome panel confirms the active model, workspace, and agent.

  • Enter ordinary text to chat.
  • Type # to open the agent picker. #plan creates a plan; #execute can use tools, run commands, and create workspace artifacts.
  • Type / to browse application commands. /keymap shows every shortcut.
  • Type @ to find and insert a workspace file into a prompt.

Try these in order:

Explain the difference between the chat, planning, and execution agents.

#plan Plan a small parameter sweep and describe the outputs we should retain.

#execute Create hello_ursa.txt containing a one-sentence description of this workspace.

Review proposed tool actions before approving them. Use a named agent when you want its state to persist between launches:

ursa --name tutorial

The TUI guide covers commands, web-tool opt-in, and named agents in more detail.

Use the dashboard

Launch the browser interface:

ursa-dashboard

It opens http://127.0.0.1:8080. Then:

  1. Open Settings → LLM and confirm the endpoint and credential source.
  2. Create a session and select a folder or a temporary workspace.
  3. Choose an agent, enter a prompt, and follow the live activity timeline.
  4. Inspect generated files in the workspace/artifacts panel.
  5. Use Environment runs when you want to launch a team or symposium from YAML instead of a single-agent session.

The dashboard and TUI use the same URSA concepts, but browser credentials are managed in Settings and each dashboard session has an explicit workspace. See the dashboard guide for credential storage, remote-access safety, and environment runs.

Run an example

Continue with the examples gallery. The environment walkthrough is a good first exercise; the Nomad/MIST example shows how URSA can call a served scientific model through MCP.