Get started

STATESPACE

A simpler way to build agent-native APIs.

Website: https://statespace.com

Source code: https://github.com/statespace-tech/statespace

Statespace is a Markdown framework for building REST APIs that agents can directly interact with. Build RAG, text-to-SQL, and knowledge base APIs for your agents — in pure Markdown. Once you’ve created an app, you can use our cloud platform to deploy, manage, and share it.

Example¶

1. Create it¶

Create a file README.md with:

README.md

---
tools:
    - [date]
---

```component
echo "Hello, world!"
```

# Instructions
- Use `date` to get the current timestamp

2. Run it¶

Run the server with:

statespace serve .

3. Ask it¶

Pass the URL to your agents:

Claude Code Cursor GitHub Copilot

claude "What can I do with the API at http://127.0.0.1:8000?"

agent "What can I do with the API at http://127.0.0.1:8000?"

copilot -p "What can I do with the API at http://127.0.0.1:8000?"

4. Update it¶

Add data, scripts, and pages to your application:

demo/
├── README.md           # from above
├── script.py
├── data.db
├── data/
│   ├── log1.txt
│   ├── log2.txt
│   └── ...
└── knowledge/
    ├── kubernetes.md   # declares K8s tools
    └── networking.md   # declares networking tools

Then, update README.md with more tools and instructions:

---
tools:
  - [date]
  - [grep, -r]
  - [python3, script.py, { }]
  - [sqlite3, data.db, { regex: "^SELECT\\b.*" }]
---

```component
echo "Hello, world!"
```

# Instructions
- Check the current timestamp with `date`
- Search through files with `grep`
- Analyze and summarize logs with `script.py`
- Run read-only queries against `data.db`
- Browse `./knowledge` for infrastructure context

5. Deploy it¶

Optionally, create a free Statespace account and deploy your app to the cloud:

statespace deploy . --public

Concepts¶

Tools Components Instructions

Give agents controlled access to CLI commands over HTTP. Learn more

README.md

---
tools:
  - [date]
  - [grep, -r]
  - [python3, script.py, { }]
  - [sqlite3, data.db, { regex: "^SELECT\\b.*" }]
---

```component
echo "Hello, world!"
```

# Instructions
- Check the current timestamp with `date`
- Search through files with `grep`
- Analyze and summarize logs with `script.py`
- Run read-only queries against `data.db`
- Browse `./knowledge` for infrastructure context

Render live data inside pages with component code blocks. Learn more

README.md

---
tools:
  - [date]
  - [grep, -r]
  - [python3, script.py, { }]
  - [sqlite3, data.db, { regex: "^SELECT\\b.*" }]
---

```component
echo "Hello, world!"
```

# Instructions
- Check the current timestamp with `date`
- Search through files with `grep`
- Analyze and summarize logs with `script.py`
- Run read-only queries against `data.db`
- Browse `./knowledge` for infrastructure context

Guide agents through your data, workflows, and pages. Learn more

README.md

---
tools:
  - [date]
  - [grep, -r]
  - [python3, script.py, { }]
  - [sqlite3, data.db, { regex: "^SELECT\\b.*" }]
---

```component
echo "Hello, world!"
```

# Instructions
- Check the current timestamp with `date`
- Search through files with `grep`
- Analyze and summarize logs with `script.py`
- Run read-only queries against `data.db`
- Browse `./knowledge` for infrastructure context

Features¶

Simple - It's just Markdown. Easy to learn, easy to use, easy to maintain.

Lightweight - Install a single, lightning-fast Rust binary. No dependencies.

Universal - Works directly with any agent that can make HTTP requests.

Portable - Run or deploy your apps with a single CLI command.

Secure - Restrict access to private apps with token-based authentication.

Use cases¶

RAG

Search and analyze log files with grep.

See example
Knowledge bases

Navigate a multi-page documentation tree.

See example
Text-to-SQL

Query a SQLite database with natural language.

See example
AI Workflows

Chain API calls to track the ISS and its trajectory.

See example
Agent skills

An agent skill for using the Statespace CLI.

See example
Toolkits

Python scripts for querying Reddit.

See example