-e BINDAI_API_KEY=your-secret-key
bindai-api
On macOS or Linux:
docker run —rm -p 8000:8000 -e BINDAI_API_KEY=your-secret-key
bindai-api The API will then be available at: http://localhost:8000 Docker Compose The repository also includes a docker-compose.yml configuration. Start the API service with: docker compose up —build Stop the service with: docker compose down The API is exposed on port 8000. A typical local deployment is: Client | v Docker Compose | v BindAI API | +---- Agents +---- Workflows +---- Automation +---- Connections | v External Providers / Services The Compose configuration can be used as a starting point for local deployment and for environments that support Docker Compose. Health Checks The BindAI API provides a public health endpoint: GET /health Example: curl http://localhost:8000/health The response contains the service status:
-H “Authorization: Bearer your-secret-key”
http://localhost:8000/api/v1/projects The following endpoint is public: GET /health Resource endpoints are protected. The v0.1 authentication implementation intentionally uses a simple environment-based API key. Persistent API-key management, user authentication, and advanced authorization are future capabilities. REST API Resources The v0.1 API exposes several resource areas. Agents Agent endpoints provide agent discovery and execution. GET /api/v1/agents POST /api/v1/agents//run POST /api/v1/agents//stream The run endpoint executes an agent synchronously. The stream endpoint provides streamed output. Workflows Workflow endpoints provide workflow discovery and execution. GET /api/v1/workflows POST /api/v1/workflows//run Workflow execution accepts variables that are passed into the workflow execution context. Projects Projects can be exposed through: GET /api/v1/projects GET /api/v1/projects/ The v0.1 API uses the configured in-process project registry. It does not provide a persistent project management database. Background Runs Background automation runs are exposed through: POST /api/v1/runs GET /api/v1/runs/ A run can be submitted and queried later using its run ID. Background Execution BindAI v0.1 provides background execution through the AutomationWorker. The worker executes automation runs in the application process using an in-process thread pool. Conceptually: API Request | v Automation Worker | v Automation Definition | v Execution This is suitable for the initial v0.1 deployment model. However, it is important to understand the current limitation: The v0.1 worker is not a distributed queue-based worker system. The worker is tied to the running application process. If the process stops, in-process work can be interrupted. For production systems that require durable distributed background processing, an external queue or persistent job system should be introduced. Queue-based execution is planned for a future BindAI release and is not required for the v0.1 release. Worker Scaling The v0.1 background worker should not be treated as a distributed worker cluster. For example, running: Application Instance A | +---- Automation Worker Application Instance B | +---- Automation Worker does not automatically provide coordinated distributed execution. Each application process has its own in-process worker. A production deployment that requires coordinated workers should use a persistent queue and worker architecture. That capability is outside the initial v0.1 scope. Environment Variables Deployment-specific configuration should remain separate from application code. Common environment variables include: BINDAI_API_KEY OPENAI_API_KEY ANTHROPIC_API_KEY GEMINI_API_KEY GROQ_API_KEY OPENROUTER_API_KEY PINECONE_API_KEY The exact variables depend on the providers, memory systems, Knowledge systems, and connections used by the application. Never commit secrets to source control. Use environment variables or a dedicated secrets-management system. Model Providers BindAI supports multiple model-provider integrations. An application can select a provider and model appropriate for its environment. Conceptually: Development | v Development Provider Production | v Production Provider Provider configuration should remain separate from application logic whenever possible. This makes it easier to change providers without redesigning the application. Memory Applications that require persistence can configure an appropriate memory provider. Depending on the BindAI configuration, memory can use storage systems such as: In-memory storage SQLite PostgreSQL Vector memory Pinecone Chroma The appropriate choice depends on the application’s persistence and retrieval requirements. For production systems, consider: Data durability Backup strategy Access control Performance Capacity Isolation Recovery procedures Persistent memory should be tested against the same deployment conditions in which the application will run. Knowledge Resources Knowledge resources should generally be prepared before an application begins serving production traffic. A typical Knowledge pipeline is: Documents | v Parsing | v Chunking | v Embeddings | v Knowledge Storage | v Retrieval Preprocessing and indexing documents ahead of time can reduce startup work and improve application readiness. For larger Knowledge systems, consider: Embedding consistency Metadata quality Index readiness Retrieval quality Filtering Reranking Data freshness Re-indexing strategy Knowledge and Model Compatibility The embedding model used to build a Knowledge index should remain compatible with the embedding model used for retrieval. For example: Documents | v Embedding Model | v Vector Index | v Retrieval Changing embedding dimensions or models may require rebuilding or migrating the affected index. Tools Production applications may depend on tools for: Databases Search File processing External APIs Notifications Business operations Tools should be tested independently before deployment. Particular attention should be given to tools that perform external side effects. Operations that create external side effects should be designed with appropriate error handling and idempotency where possible. Connections BindAI Connections provide integrations with external services. Current integrations include: Webhooks GitHub Slack Notion Jira Discord Resend Vercel Netlify Google Sheets Google Docs Gmail Google Drive A deployment should provide the credentials and configuration required by the connections it uses. External integrations should also be tested against the intended production environment. Scheduled Workflows Workflows can be combined with scheduling to automate recurring work. Examples include: Reports Synchronization Document processing Maintenance Notifications A conceptual deployment looks like: Scheduler | v Workflow | +---- Agent +---- Tool +---- Knowledge | v Result Scheduling infrastructure is deployment-dependent. The application must provide an appropriate scheduler or scheduling environment for recurring production execution. BindAI’s workflow scheduling capabilities should not be confused with a distributed scheduling platform. Human Tasks Applications that use human-in-the-loop workflows require a mechanism for users to receive and complete pending tasks. Conceptually: Workflow | v Human Task | v Application UI | v Human Decision | v Workflow Continuation The user interface, authentication, persistence, and task-management infrastructure are deployment concerns unless explicitly provided by the application. Logging Production applications should capture useful operational information. Examples include: Agent execution Workflow execution Tool execution Provider failures Retry activity Timeout events Connection failures Knowledge retrieval failures API request failures Background run failures Avoid logging sensitive information unnecessarily. API keys, credentials, private user data, and other secrets should never be written to ordinary application logs. Observability BindAI provides an event system that can be used as a foundation for application observability. Execution events can include: Agent started Agent finished Model requested Model responded Tool executed Workflow started Workflow finished Node started Node completed Memory read Memory written MCP connection events BindAI Runtime also provides an in-memory EventRecorder that can record events emitted through an execution context’s event bus. This can be used as a foundation for: Debugging Execution inspection Custom logging Metrics integrations Future tracing integrations The current implementation is not a complete hosted observability platform. External monitoring, metrics, tracing, dashboards, and alerting remain deployment concerns. Monitoring Production systems benefit from monitoring application health and execution behavior. Useful signals can include: API request volume API error rates Execution duration Provider latency Tool failures Workflow failures Background run failures Retry frequency Timeout frequency Memory errors Connection failures The /health endpoint can provide a basic service-health signal. More advanced monitoring can be implemented using the surrounding infrastructure. Error Handling Production applications should define how failures are handled. Possible failure sources include: Model providers Tools Knowledge retrieval Memory providers Connections Workflow operations External services API requests Background workers A conceptual flow is: Execution | +---- Success ---> Result | +---- Failure ---> Error Handling Retries and timeouts can improve resilience when used appropriately. They should not be used blindly for operations that have non-idempotent external side effects. Reliability Reliable deployments usually combine several layers of protection. Examples include: Input validation Error handling Retries Timeouts Persistent storage Health checks Logging Monitoring Backups Controlled deployments The appropriate reliability strategy depends on the application’s workload and failure modes. For background automation, remember that the v0.1 worker is process-local and does not provide durable distributed queue semantics. Scaling A deployment may eventually require multiple application instances. Conceptually: Load Balancer | +---- Application Instance A +---- Application Instance B +---- Application Instance C However, horizontal scaling is not automatic simply because an application uses BindAI. Before running multiple instances, verify that application state and external resources support the deployment model. Important considerations include: Shared databases Memory persistence Workflow state Scheduler coordination Connection management Idempotency Concurrent execution Task ownership Background worker coordination Stateful components require particular attention when scaling horizontally. The v0.1 in-process automation worker does not provide cross-instance coordination. Stateless vs Stateful Components A useful deployment distinction is: Stateless Components can usually be recreated without losing important application state. Examples may include: Agent configuration Tool definitions Workflow definitions Application code API application processes Stateful Components retain information required across executions. Examples include: Persistent Memory Knowledge indexes Databases Workflow state Human Task state Background run state Stateful resources require appropriate persistence and backup strategies. Deployment Environments Applications commonly use separate environments. Development | v Staging | v Production Each environment can have different: Providers Databases Knowledge indexes Credentials External integrations Configuration Logging settings Separating environments reduces the risk of development activity affecting production systems. Database and Storage Considerations If an application uses persistent storage, the deployment should define: Connection configuration Schema management Backups Recovery procedures Access control Capacity Monitoring Persistent storage should not depend on temporary local process state when data must survive restarts. This is particularly important when deploying multiple application instances. Containerized Deployment BindAI v0.1 can be packaged into a standard Python container. The repository includes a Dockerfile that: Starts from Python 3.12. Copies the BindAI workspace into the container. Installs uv. Synchronizes workspace dependencies. Exposes port 8000. Starts the BindAI API with Uvicorn. The conceptual container structure is: Container ├── Application Code ├── BindAI Packages ├── Python Dependencies └── Configuration The container runtime, orchestration platform, networking, storage, and secrets management remain deployment-environment concerns. Docker Environment Configuration When running the BindAI API in Docker, provide required environment variables explicitly. For example: docker run —rm -p 8000:8000
-e BINDAI_API_KEY=your-secret-key
-e OPENAI_API_KEY=your-openai-key
bindai-api Do not hardcode secrets into: Dockerfiles Source code Docker images Git repositories Public configuration files For production deployments, use the secret-management capabilities provided by the hosting environment. API Deployment Example A simple BindAI API deployment can look like: Client | | Authorization: Bearer your-secret-key v BindAI API | +---- Agent | +---- Workflow | +---- Project | +---- Background Run | v External Providers / Services The API provides the HTTP boundary. The BindAI application provides the agents, workflows, tools, connections, and runtime behavior. The hosting environment provides the infrastructure around the API. Production API Considerations When exposing the BindAI API publicly, consider: TLS termination Network access controls API key protection Rate limiting Request limits Logging Monitoring Secret management Process supervision Persistent storage Backups The v0.1 API authentication layer provides a simple API key mechanism. It does not provide a complete user-management, OAuth, RBAC, or multi-tenant authorization system. Those capabilities can be added by the surrounding application or in future BindAI releases. Deployment Validation Before releasing an application, validate: Provider configuration Agent behavior Workflow execution Tool execution Knowledge retrieval Memory persistence Connection credentials API authentication API health checks Background run behavior Scheduled operations Human-task flows Error handling Run tests against an environment that resembles production as closely as practical. For the BindAI repository, the main test suite can be run with: uv run pytest tests -q The API package tests can be run with: uv run pytest packages/bindai-api/tests -q The Connections package tests can be run with: uv run pytest packages/bindai-connections/tests -q Deployment Checklist Before deployment: Validate agents. Validate workflows. Test tools. Configure model providers. Verify environment variables. Configure persistent storage where required. Prepare Knowledge indexes. Configure Memory providers. Configure required Connections. Test external integrations. Configure BINDAI_API_KEY when exposing the REST API. Test /health. Test authenticated API endpoints. Test background runs. Review logging behavior. Review security permissions. Test failure handling. Validate scheduled workflows where applicable. Validate human-task flows where applicable. Run end-to-end tests. Security Checklist Before production deployment: Remove secrets from source code. Use secure credential storage. Limit provider permissions. Limit database permissions. Restrict external integrations. Validate tool inputs. Protect state-changing operations. Protect API endpoints. Protect human-task endpoints. Avoid sensitive information in logs. Separate development and production credentials. Review data-access boundaries. Use HTTPS for externally exposed APIs. Rotate credentials when appropriate. Release Strategy Production deployments should be released in controlled steps. A simple process is: Develop | v Test | v Build | v Stage | v Validate | v Deploy | v Monitor For important applications, consider: Versioned releases Rollbacks Migration plans Health checks Post-deployment validation Backup and recovery procedures Current BindAI v0.1 Deployment Scope BindAI v0.1 provides: Python application execution REST API API key authentication Agent execution endpoints Agent streaming endpoints Workflow execution endpoints Project endpoints Background automation run endpoints Health checks Docker deployment Docker Compose deployment In-process background workers Runtime execution events In-memory event recording Connections and external integrations The v0.1 deployment model is intentionally lightweight. It is designed to provide a usable public API and deployment foundation without requiring a distributed infrastructure stack. Not Yet Required for v0.1 The following capabilities are not required to release BindAI v0.1: Distributed job queues Durable distributed workers Kubernetes deployment Automatic horizontal worker coordination Managed cloud deployment Built-in multi-tenant infrastructure Built-in billing Enterprise RBAC Hosted observability dashboards These capabilities can be added after the initial public release. Queue-based execution is particularly important for future distributed background workloads, but it should not block the v0.1 release. Future Distributed Deployment A future distributed architecture can introduce a persistent queue: Client | v BindAI API | v Persistent Queue | +---- Worker A +---- Worker B +---- Worker C | v Persistent State / External Services This architecture would allow background execution to survive individual API process lifecycles and support multiple coordinated workers. Queue-based execution is outside the current v0.1 deployment scope. Kubernetes Kubernetes is also outside the initial v0.1 deployment scope. A future Kubernetes deployment could provide: Multiple API replicas Multiple worker replicas Service discovery Rolling deployments Autoscaling Health checks Persistent volumes Secret management These capabilities should be introduced when the underlying distributed execution model requires them. For v0.1, Docker and Docker Compose provide the supported container deployment foundation. Summary Deployment packages BindAI application components into an environment where they can be used reliably. A v0.1 deployment may combine: Client | v BindAI REST API | +---- Agents +---- Workflows +---- Tools +---- Knowledge +---- Memory +---- Connections +---- Automation | v External Providers / Services The application can be deployed directly with Python or through Docker and Docker Compose. BindAI v0.1 provides a REST API, API-key authentication, streaming, background automation runs, runtime events, and a lightweight deployment foundation. The current background worker is process-local. Durable queue-based execution and distributed workers are planned for future releases. The surrounding deployment infrastructure remains responsible for: Hosting Networking TLS Secrets Persistent storage Backups Monitoring Scaling Process management Keeping these responsibilities separate allows BindAI applications to move from local development to staging and production without requiring the framework itself to manage every aspect of infrastructure.