# Bluebag

> Bluebag is infrastructure for building reliable AI agents. It provides isolated sandbox runtimes, versioned procedures, customer context, built-in tools, and self-improvement loops — so agents execute real workflows predictably across any LLM.

Most agents work in demos but break in production. Bluebag is the missing layer: execution, memory, self-improvement, and repeatable procedures. Ships TypeScript SDKs for Vercel AI SDK and LangChain. Works with any LLM: OpenAI, Anthropic, Google Gemini, Llama, DeepSeek, Mistral, Grok, and others.

Key concepts:

- **Execution**: Each agent session gets an isolated virtual machine where it can run bash commands, execute code (Python, JavaScript, TypeScript), read and write files, and install dependencies. Sandboxes support 10,000+ concurrent sessions with sub-50ms response times.
- **Customer Context**: Preserve user-specific context across sessions. Agents recognize users, carry forward preferences, and respond with continuity instead of starting fresh every time.
- **Procedures**: Versioned, deterministic procedures with scripts and built-in validation. Important work runs the same way every time — unlike prompts, which drift.
- **Self-Improving**: Agents learn from real interactions. Failures, edge cases, and repeated friction become proposed improvements your team can review. Behavior sharpens over time without losing control.
- **Sandbox**: Isolated VM per session for safe execution. Sandboxes auto-recover if lost, maintain filesystem state, and clean up automatically.
- **Session**: A stateful execution context backed by Redis. Sessions track the sandbox, loaded procedures, file cache, and system prompt. Sessions auto-reinitialize if the sandbox is lost.
- **Tools**: Five built-in tools are provided to every agent — `bluebag_bash` (run shell commands), `bluebag_code_execution` (run Python/JS/TS), `bluebag_text_editor` (view/create/edit files), `bluebag_computer_use` (desktop control), and `bluebag_file_download_url` (generate download URLs for files created in the sandbox).
- **Stable ID**: Multi-tenant isolation identifier. Each stable ID gets its own sandbox, so different end-users of the same application have isolated execution environments.

Integration requires 3 lines of code:

```typescript
import { Bluebag } from "@bluebag/ai-sdk";
const bluebag = new Bluebag({ apiKey: process.env.BLUEBAG_API_KEY });
const config = await bluebag.enhance({ model, messages });
```

npm packages: `@bluebag/ai-sdk` (Vercel AI SDK), `@bluebag/langchain` (LangChain), `@bluebag/cli` (CLI), `@bluebag/core` (shared types and utilities).

## Docs

- [Introduction](https://www.bluebag.ai/docs): What Bluebag is, what you can build, and core concepts
- [API Keys](https://www.bluebag.ai/docs/getting-started/api-keys): Create a Bluebag API key for server-side use
- [Quickstart — Vercel AI SDK](https://www.bluebag.ai/docs/quickstart/ai-sdk): Get started with `@bluebag/ai-sdk` in minutes
- [Quickstart — LangChain](https://www.bluebag.ai/docs/quickstart/langchain): Get started with `@bluebag/langchain` in minutes
- [Quickstart — Node.js](https://www.bluebag.ai/docs/quickstart/nodejs): Get started with the core SDK directly

## Procedures Guides

- [Procedures Overview](https://www.bluebag.ai/docs/guides/skills): What procedures are, how they work, progressive disclosure model, and format
- [Creating Procedures](https://www.bluebag.ai/docs/guides/skills/creating-skills): All methods for creating and uploading procedures (dashboard, CLI, GitHub import, skills.sh)
- [Writing Procedures](https://www.bluebag.ai/docs/guides/skills/writing-skills): Best practices for writing effective procedure files
- [Procedure Format](https://www.bluebag.ai/docs/guides/skills/skill-format): Detailed reference for procedure structure and frontmatter
- [Accepted File Types](https://www.bluebag.ai/docs/guides/skills/accepted-files): Allowed file extensions for procedure uploads (.md, .txt, .json, .yaml, .py, .js, .ts, .sh, .pdf, and more)
- [Runtime Dependencies](https://www.bluebag.ai/docs/guides/skills/runtime-dependencies): How to declare Python and Node.js dependencies in procedures
- [GitHub Import](https://www.bluebag.ai/docs/guides/skills/github-import): Import procedures from any public GitHub repository
- [skills.sh Import](https://www.bluebag.ai/docs/guides/skills/skillssh-import): Import procedures from the skills.sh marketplace
- [CLI Push](https://www.bluebag.ai/docs/guides/skills/cli-push): Push local procedures to Bluebag via CLI

## Vercel AI SDK Guides

- [AI SDK Overview](https://www.bluebag.ai/docs/guides/ai-sdk): Guides for building with `@bluebag/ai-sdk`
- [Tool Calls](https://www.bluebag.ai/docs/guides/ai-sdk/tool-calls): Making and handling tool calls with the AI SDK
- [Handling Files](https://www.bluebag.ai/docs/guides/ai-sdk/handling-files): Upload, download, and persist files in Bluebag sessions
- [Stable ID](https://www.bluebag.ai/docs/guides/ai-sdk/stable-id): Multi-tenant isolation with stable IDs
- [Restricting Procedures](https://www.bluebag.ai/docs/guides/ai-sdk/restricting-skills): Scope procedures per session with `activeSkills`
- [UI Tool Types](https://www.bluebag.ai/docs/guides/ai-sdk/ui-tool-types): Type-safe tool results for rendering in React UIs

## LangChain Guides

- [LangChain Overview](https://www.bluebag.ai/docs/guides/langchain): Guides for building with `@bluebag/langchain`
- [Tool Calls](https://www.bluebag.ai/docs/guides/langchain/tool-calls): Making and handling tool calls with LangChain
- [Handling Files](https://www.bluebag.ai/docs/guides/langchain/handling-files): Upload, download, and persist files in Bluebag sessions
- [Stable ID](https://www.bluebag.ai/docs/guides/langchain/stable-id): Multi-tenant isolation with stable IDs
- [Restricting Procedures](https://www.bluebag.ai/docs/guides/langchain/restricting-skills): Scope procedures per session with `activeSkills`

## CLI Guides

- [CLI Overview](https://www.bluebag.ai/docs/guides/cli): Install and get started with the Bluebag CLI (`npm install -g @bluebag/cli`)
- [Authentication](https://www.bluebag.ai/docs/guides/cli/authentication): Device-based authentication flow
- [Pushing Procedures](https://www.bluebag.ai/docs/guides/cli/pushing-skills): Upload local procedures to the cloud with `bluebag push`
- [Pulling Procedures](https://www.bluebag.ai/docs/guides/cli/pulling-skills): Download remote procedures to your workspace with `bluebag pull`
- [Conflict Resolution](https://www.bluebag.ai/docs/guides/cli/conflict-resolution): Resolve sync conflicts between local and remote procedures
- [Command Reference](https://www.bluebag.ai/docs/guides/cli/command-reference): Full list of CLI commands and options
- [Best Practices](https://www.bluebag.ai/docs/guides/cli/best-practices): Recommended workflows for teams
- [Troubleshooting](https://www.bluebag.ai/docs/guides/cli/troubleshooting): Common issues and solutions
- [Validation](https://www.bluebag.ai/docs/guides/cli/validation): Procedure validation rules and file constraints

## API Reference

- [AI SDK Reference](https://www.bluebag.ai/docs/reference/ai-sdk): Full API reference for `@bluebag/ai-sdk`
- [LangChain Reference](https://www.bluebag.ai/docs/reference/langchain): Full API reference for `@bluebag/langchain`

## Product

- [Pricing](https://www.bluebag.ai/pricing): Starter (free, 5h sandbox runtime, 50 procedures), Pro ($20/mo, 25h runtime, 5000 procedures, team collaboration), Enterprise (unlimited, 99.99% SLA)
- [Playground](https://www.bluebag.ai/playground): Test procedures and agent behavior in the browser before deploying
- [Community](https://discord.com/invite/ctQUHEPpjw): Join the Bluebag Discord community

## Blog

- [What Are Agent Skills?](https://www.bluebag.ai/blog/what-are-agent-skills): Comprehensive guide to agent procedures — what they are, how they work, and why they matter
- [The Complete Guide to AI Agent Skills](https://www.bluebag.ai/blog/complete-guide-agent-skills): From prototype to production with agent procedures
- [Anthropic Was Right About Agent Skills](https://www.bluebag.ai/blog/anthropic-was-right-about-agent-skills): Why structure beats prompts for reliable agents
- [Add Skills to Your AI-SDK Agent](https://www.bluebag.ai/blog/add-skills-to-your-ai-sdk-agent-in-minutes): Step-by-step guide for Vercel AI SDK integration
- [Add Skills to Your LangChain Agent](https://www.bluebag.ai/blog/add-skills-to-your-langchain-agent-in-minutes): Step-by-step guide for LangChain integration
- [Import GitHub Skill Repos](https://www.bluebag.ai/blog/import-github-skill-repos-into-bluebag): One-URL import from any public GitHub repo
- [Your AI Agent Has an Onboarding Problem](https://www.bluebag.ai/blog/your-ai-agent-has-an-onboarding-problem): Why treating agents like new hires produces better results
- [AI Agent Observability](https://www.bluebag.ai/blog/ai-agent-observability-debugging): How to debug when your agent breaks in production
- [Sandboxed Code Execution Security](https://www.bluebag.ai/blog/sandboxed-code-execution-security): Security best practices for agents that execute code
- [Building Agents That Don't Break](https://www.bluebag.ai/blog/building-agents-that-dont-break): The infrastructure checklist for reliable agents

## Optional

- [About the Team](https://www.bluebag.ai/docs/about/meet-the-team): Bluebag's story and mission
- [Privacy Policy](https://www.bluebag.ai/privacy-policy): Data handling and privacy practices
- [Terms of Service](https://www.bluebag.ai/terms-of-service): Terms of use
- [How to Avoid LLM Vendor Lock-in](https://www.bluebag.ai/blog/avoid-llm-vendor-lock-in): Architecting agents for portability across LLM providers
- [Claude Desktop Skills vs Production Agent Skills](https://www.bluebag.ai/blog/claude-desktop-skills-vs-production-agent-skills): What changes when you go from demo to deployment
- [Why Your Agent Demo Works But Production Breaks](https://www.bluebag.ai/blog/why-agent-demo-works-production-breaks): The gap between demos and production agents