instanode

Official Python SDK for instanode.dev — zero-setup Postgres databases and webhook receivers for AI agents and humans. No Docker, no account for the free tier.

pip install instanode

Quickstart

import instanode

client = instanode.Client()

# Postgres (pgvector pre-installed). Free tier: 10 MB / 2 connections / 24h TTL.
db = client.provision_database(name="my-app")
print(db.connection_url)   # postgres://…@pg.instanode.dev:5432/db_…

# Webhook receiver. Free tier: 100 requests stored / 24h TTL.
hook = client.provision_webhook(name="stripe-events")
print(hook.connection_url) # https://api.instanode.dev/webhook/receive/<token>

Use db.connection_url with psycopg, asyncpg, SQLAlchemy, Prisma, Drizzle, or anything else that speaks Postgres.

Async

import asyncio
import instanode.aio

async def main():
    async with instanode.aio.AsyncClient() as client:
        db = await client.provision_database(name="my-app")
        print(db.connection_url)

asyncio.run(main())

Paid tier

The free tier caps each /24 subnet at 5 provisions/day and resources expire in 24 hours. To lift the caps and make resources permanent, sign up at instanode.dev, mint a bearer token from the dashboard, and set it:

client = instanode.Client(api_key="eyJ…")
# Or via env: export INSTANODE_API_KEY=eyJ…

Account operations (paid tier)

# Claim an anonymous resource into the account (clears the 24h expiry).
client.claim(token=db.token)

# List everything this account owns.
for r in client.list_resources():
    print(r.resource_type, r.token, r.tier, r.created_at)

# Delete a resource.
client.delete_resource(db.token)

# Mint a fresh 30-day JWT from a session-authenticated context.
jwt = client.get_api_token()

Error handling

from instanode import InstanodeError

try:
    client.provision_database(name="my-app")
except InstanodeError as e:
    if e.is_rate_limited():
        # …retry later
        ...
    elif e.is_unauthorized():
        # …bad or missing API key
        ...
    else:
        raise

InstanodeError exposes status_code, code, and message, plus convenience checks: is_not_found(), is_unauthorized(), is_forbidden(), is_rate_limited(), is_conflict(), is_service_unavailable().

Scope

This 0.3.0 release covers what the live API actually exposes today:

• POST /db/new → provision_database
• POST /webhook/new → provision_webhook
• POST /api/me/claim → claim
• GET /api/me/resources → list_resources
• DELETE /api/me/resources/{token} → delete_resource
• GET /api/me/token → get_api_token

Monitor/heartbeat, cache (Redis), MongoDB, NATS queue, and credential rotation are on the roadmap. They live on the feature/full-api branch and will land in a later minor release once the backend ships them. Pin to that branch explicitly if you want the preview surface today:

pip install git+https://github.com/InstaNode-dev/sdk-python.git@feature/full-api

Related

• MCP server (Claude Code / Cursor / Windsurf): https://www.npmjs.com/package/@instanode/mcp
• LangChain tools: https://pypi.org/project/langchain-instanode/
• LlamaIndex tools: https://pypi.org/project/llama-index-tools-instanode/
• CrewAI tools: https://pypi.org/project/crewai-instanode-tools/
• HTTP API reference: https://instanode.dev/llms.txt

License

MIT. See LICENSE.