> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SurrealDB Database Backend

> Configure SurrealDB with its client, URL, credentials, namespace, and database instead of a SQL connection string.

Configure SurrealDB with its client, URL, credentials, namespace, and database instead of a SQL connection string. Local defaults match ./cookbook/scripts/run\_surrealdb.sh.

```python surreal.py theme={null}
"""
SurrealDB Database Backend
==========================

Configure SurrealDB with its client, URL, credentials, namespace, and database
instead of a SQL connection string. Local defaults match
./cookbook/scripts/run_surrealdb.sh.

Prerequisites: OPENAI_API_KEY, agno[surrealdb], and run_surrealdb.sh
Run: .venvs/demo/bin/python cookbook/05_agent_os/02_databases/surreal.py
Try: Open http://localhost:7777/config and inspect os_database
"""

from os import getenv

from agno.agent import Agent
from agno.db.surrealdb import SurrealDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

# ---------------------------------------------------------------------------
# Create Database
# ---------------------------------------------------------------------------

db = SurrealDb(
    client=None,
    db_url=getenv("SURREALDB_URL", "ws://localhost:8000"),
    db_creds={
        "username": getenv("SURREALDB_USER", "root"),
        "password": getenv("SURREALDB_PASSWORD", "root"),
    },
    db_ns=getenv("SURREALDB_NAMESPACE", "agno"),
    db_db=getenv("SURREALDB_DATABASE", "agent_os"),
    id="agent-os-surreal",
)

# ---------------------------------------------------------------------------
# Create Agent and AgentOS
# ---------------------------------------------------------------------------

surreal_agent = Agent(
    id="surreal-agent",
    name="SurrealDB Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    instructions="Answer questions concisely.",
    markdown=True,
)

agent_os = AgentOS(
    id="surreal-agent-os",
    description="AgentOS backed by SurrealDB.",
    db=db,
    agents=[surreal_agent],
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run AgentOS
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    agent_os.serve(app="surreal:app", reload=True)
```

## Run the Example

<Steps>
  <Snippet file="create-venv-step.mdx" />

  <Step title="Install dependencies">
    ```bash theme={null}
    uv pip install -U "agno[os]" openai surrealdb
    ```
  </Step>

  <Step title="Export your OpenAI API key">
    <CodeGroup>
      ```bash Mac/Linux theme={null}
      export OPENAI_API_KEY="your_openai_api_key_here"
      ```

      ```bash Windows theme={null}
      $Env:OPENAI_API_KEY="your_openai_api_key_here"
      ```
    </CodeGroup>
  </Step>

  <Step title="Run SurrealDB">
    ```bash theme={null}
    docker run -d --rm --name surrealdb --pull always -p 8000:8000 surrealdb/surrealdb:latest start --user root --pass root
    ```
  </Step>

  <Step title="Run the example">
    Save the code above as `surreal.py`, then run:

    ```bash theme={null}
    python surreal.py
    ```
  </Step>
</Steps>

Full source: [cookbook/05\_agent\_os/02\_databases/surreal.py](https://github.com/agno-agi/agno/blob/v3.0.4/cookbook/05_agent_os/02_databases/surreal.py)