Getting started with Arachne

This tutorial takes you from a fresh clone to your first executed agent graph.

Arachne turns a natural-language goal into a typed graph, executes the graph in dependency-aware waves, stores the session, and repairs the run when evaluation fails.

graph LR
    A[Install]
    B[Configure]
    C[Run]
    D[Inspect]
    E[Reuse]
    A --> B
    B --> C
    C --> D
    D --> E

Prerequisites

• Python 3.11 or newer
• uv
• Access to at least one LLM provider or a local Ollama model
• Git

1. Clone the repository

git clone https://github.com/Strategic-Automation/arachne.git
cd arachne

2. Run the quickstart wizard

./quickstart.sh

The wizard helps with:

1. dependency installation
2. provider selection
3. local runtime settings
4. tool availability checks
5. first-run guidance

If you prefer manual setup:

uv sync --all-groups

3. Understand the local files

Arachne keeps private credentials separate from structured settings.

graph TD
    A[Runtime overrides]
    B[Selected YAML]
    C[Defaults]
    D[Settings]
    A --> D
    B --> D
    C --> D

File	Purpose	Commit it?
local override file	private provider credentials and local overrides	No
arachne.yaml	model, budget, observability, and session settings	Usually no
.venv/	local virtual environment	No

4. Run your first graph

uv run arachne run "Research the current state of humanoid robotics"

Arachne will:

1. parse the goal
2. weave a graph topology
3. provision tools and skills
4. execute nodes in waves
5. evaluate the result
6. persist the session

graph TD
    A[Goal]
    B[Weave graph]
    C[Execute graph]
    D[Save session]
    E[Evaluate]
    F[Render output]
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

5. Use interactive mode for complex goals

Interactive mode gives you a chance to clarify and review the generated plan before execution.

uv run arachne run "Research a company" --interactive

Use it when:

• the goal is broad or ambiguous
• you want to inspect the graph before it runs
• the output affects a real decision
• you want to steer the plan while developing a workflow

6. Inspect your session

List recent runs:

uv run arachne ls -n 5

Read the latest result:

uv run arachne cat last

List cached graph topologies:

uv run arachne graphs

7. Reuse or resume work

Re-run a successful topology against a fresh session:

uv run arachne rerun <graph-id>

Resume a failed or interrupted session:

uv run arachne resume <session-id>

graph TD
    A[Saved session]
    B[View output]
    C[Resume]
    D[Reuse graph]
    E[Inspect graph]
    A --> B
    A --> C
    A --> D
    A --> E

Example workflow

# 1. Run a research goal
uv run arachne run "Map the open-source agent runtime landscape"

# 2. Inspect the result
uv run arachne cat last

# 3. List the graph cache
uv run arachne graphs

# 4. Reuse a good topology for a related goal
uv run arachne rerun <graph-id> --goal "Map the open-source evaluation framework landscape"

Troubleshooting

Symptom	Try this
uv is missing	Install uv, then rerun ./quickstart.sh
provider credential missing	update your local settings and rerun the command
no cached graphs	run arachne weave or arachne run first
session not found	run arachne ls and copy the session id exactly
output too large	check session outputs and pointer files in the run directory

Next steps

• Read the Architecture deep dive
• Browse the CLI reference
• Learn how to add custom skills
• Review the developer guide