bastionik 0.1.1

Python SDK for the Bastionik AI agent trust boundary API

bastionik-python

Python SDK for Bastionik — the trust boundary service for AI agents.

Stop hardcoding API keys in your agents. Bastionik gives every agent a cryptographic identity, stores credentials in an encrypted vault, enforces fine-grained access policies, and keeps a complete audit trail. Your agent never sees the token.

Status: Early access. Self-hosted only. Hosted version coming soon.

---

How it works

Your agent          Bastionik                   External API
    │                   │                            │
    │──── execute() ───►│                            │
    │    (signed with   │── verify Ed25519 sig       │
    │     private key)  │── check policy             │
    │                   │── decrypt credential       │
    │                   │────────────────────────────►
    │                   │◄────────────────────────────
    │◄── result ────────│   (credential deleted      │
    │                   │    from memory)            │

1. You register an agent with its Ed25519 public key
2. You store an encrypted credential (the agent never sees it)
3. You define a policy: what actions the agent is allowed to take
4. The agent signs execution requests with its private key
5. Bastionik verifies the signature, checks the policy, executes the call, returns the result

---

Requirements

• Python 3.10+
• A running Bastionik instance (core repo)

---

Installation

pip install git+https://github.com/bastionik/bastionik-python.git

Or clone and install in editable mode for development:

git clone https://github.com/bastionik/bastionik-python.git
cd bastionik-python
pip install -e .

---

Quickstart

1. Start Bastionik locally

# In your bastionik/core repo
docker compose up

The API will be available at http://localhost:8000.

2. Generate a keypair for your agent

import bastionik

keys = bastionik.generate_keypair()
# {
#   "private_key_hex": "...",   ← store this securely, pass to BastionikClient
#   "public_key_hex":  "...",   ← register agents with this
# }

3. Register, configure, and run

from bastionik import BastionikClient

client = BastionikClient(
    base_url="http://localhost:8000",
    user_id="your-user-id",                              # management plane auth
    agent_private_key=bytes.fromhex(keys["private_key_hex"]),  # signs execute requests
)

# Register the agent
agent = client.register_agent(
    name="my-github-agent",
    public_key=keys["public_key_hex"],
)
agent_id = agent["id"]

# Store a credential — the agent will never see this token directly
client.store_credential(
    agent_id=agent_id,
    service="github",
    token="ghp_your_github_token",
)

# Define what the agent is allowed to do
client.create_policy(
    agent_id=agent_id,
    service="github",
    allowed_actions=["get_repo", "list_prs", "create_issue"],
    rate_limit=100,
)

# Execute a signed action
result = client.execute(
    agent_id=agent_id,
    service="github",
    action="get_repo",
    params={"owner": "octocat", "repo": "Hello-World"},
)
print(result["full_name"])  # octocat/Hello-World

---

API Reference

BastionikClient(base_url, user_id, agent_private_key, timeout)

Parameter	Type	Default	Description
base_url	str	http://localhost:8000	URL of your Bastionik instance
user_id	str	None	Developer user ID for management operations
agent_private_key	bytes	None	Ed25519 private key bytes for signing agent requests
timeout	float	30.0	Request timeout in seconds

Management methods

These require user_id to be set.

Method	Description
register_agent(name, public_key, description)	Register a new AI agent
store_credential(agent_id, service, token)	Encrypt and store an API credential
delete_credential(agent_id, service)	Remove a stored credential
create_policy(agent_id, service, allowed_actions, rate_limit)	Define agent permissions
list_policies(agent_id)	List all policies for an agent
delete_policy(policy_id)	Delete a policy

Execution methods

These require agent_private_key to be set.

Method	Description
execute(agent_id, service, action, params)	Execute a signed agent action

Utilities

Method	Description
health()	Check server connectivity
bastionik.generate_keypair()	Generate a new Ed25519 keypair

---

Supported services and actions

GitHub (service="github")

Action	Params	Description
get_repo	owner, repo	Get repository details
list_repos	owner	List repositories for a user/org
list_prs	owner, repo	List open pull requests
create_pr	owner, repo, title, body, head, base	Create a pull request
create_issue	owner, repo, title, body	Create an issue
merge_pr	owner, repo, pull_number	Merge a pull request
close_issue	owner, repo, issue_number	Close an issue

More integrations are on the roadmap. Request one →

---

Running the example

git clone https://github.com/bastionik/bastionik-python.git
cd bastionik-python

# Install dependencies
pip install -e .

# Set your GitHub token
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_REPO=your-username/your-repo

# Run the demo (requires Bastionik running locally)
python examples/github_demo.py

---

Running tests

Tests use mocked HTTP — no live server required.

pip install -e ".[dev]"
pytest tests/ -v

---

Error handling

All API errors raise BastionikError:

from bastionik import BastionikError

try:
    result = client.execute(agent_id=agent_id, service="github", action="delete_repo", params={...})
except BastionikError as e:
    print(e.status_code)   # e.g. 403
    print(e.detail)        # raw error body from the API

Common status codes:

Code	Meaning
401	Invalid or missing Ed25519 signature
403	Action not permitted by policy
404	Agent or credential not found
409	Agent already registered
429	Rate limit exceeded

---

Security model

• Credentials never leave the vault unencrypted. Tokens are Fernet-encrypted (AES-128-CBC + HMAC-SHA256) before PostgreSQL storage and decrypted in memory only during execution.
• Every request is signed. Ed25519 signatures verify agent identity on each /execute call. Replay attacks are prevented by a 5-minute timestamp window.
• Policies are enforced server-side. Even if an agent's private key is compromised, it can only perform actions explicitly listed in its policy.
• Complete audit trail. Every action is logged before execution. You can prove exactly what every agent did, when, and with what parameters.

---

Hosted version

A hosted version of Bastionik (pip install bastionik pointing at api.bastionik.com) is in development. Sign up for early access at bastionik.com.

---

License

MIT