# Configure Stakpak

## Configuring Stakpak

If you want to read more about whats the difference between Stakpak Cloud and Stakpak Open Source and Stakpak Enterprise you can check this: [oss-vs-cloud-vs-enterprise](https://stakpak.gitbook.io/docs/get-started/oss-vs-cloud-vs-enterprise "mention")

{% hint style="success" %}
Did you know you can set up [profiles](https://stakpak.gitbook.io/docs/how-it-works/profiles "mention") so you can save and switch between multiple Stakpak configurations?\
\
Each profile will have its own provider, API keys, and model settings, so you can easily move between work, personal, and testing environments without changing your global setup.
{% endhint %}

### Stakpak Cloud

When you connect to the **Stakpak Cloud**, you unlock advanced capabilities designed for team collaboration, evolving intelligence, and workflows, including:

* Shared [rulebooks](https://stakpak.gitbook.io/docs/how-it-works/rulebooks "mention"), Sessions, and [memory](https://stakpak.gitbook.io/docs/how-it-works/memory "mention")
* Agent Recovery (coming soon)
* Intelligent Context Management (coming soon)
* Fast Documentation Research
* Discord support

1. Choose "Use Stakpak API" 

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2F9BkHakFjuo8sr6Tns3GU%2Fimage.png?alt=media&#x26;token=98689f1e-b2be-4d87-b340-778f150d1ab5" alt=""><figcaption></figcaption></figure>

2. Then it will automatically open the browser and check if you are signed in, if not then you will be redirected to sign in/register.

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FHTXRmQbSWOBxAOjmzUmG%2Fimage.png?alt=media&#x26;token=47d057b8-cc87-4ea6-9ad8-cd509cf3efab" alt=""><figcaption></figcaption></figure>

3. Then you will be redirected to the api key page, and it will be copied automatically and sent to your terminal

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FEPuCxxtCkH9kkzaBPIvZ%2Fimage.png?alt=media&#x26;token=695e52cb-0a39-443f-81d1-9303b4eebcdf" alt=""><figcaption></figcaption></figure>

Now, you can close your browser

That's it, we are ready to use Stakpak🥳

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FYMnXKEe2U9SPbVmamt7V%2Fimage.png?alt=media&#x26;token=af0417d2-9749-428c-8e85-4d913cc70eea" alt=""><figcaption></figcaption></figure>

### Stakpak Open Source

You can use Stakpak entirely offline with the **open source edition**. It runs fully in your environment with your own key and requires no connection to the Stakpak API (except for fetching public Rulebooks from the Stakpak Registry, which is an unauthenticated API)

1. Use the arrow keys to choose "Use my own Model/API Key," then press enter

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FRpWSS2I40fLGMDI376ob%2Fsfads.png?alt=media&#x26;token=084e61c8-a5ca-439f-b59e-8dd590f3c5cc" alt=""><figcaption></figcaption></figure>

2. Choose whether you want to use your own provider key or your own model

{% stepper %}
{% step %}

### Use Your Own Provider Key

1. Choose your provider (Anthropic, Google, OpenAI), then press enter

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FErtA4zoqUFFmavoRWSrY%2Fimage.png?alt=media&#x26;token=7cb4346a-1764-4f3d-a99d-424707a8e632" alt=""><figcaption></figcaption></figure>

2. Paste your provider's API Key and press enter

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FG7qNhNJdkGOCX4iyzO40%2Fimage.png?alt=media&#x26;token=589c652f-0b47-41ff-b364-0a0727761d03" alt=""><figcaption></figcaption></figure>

That's it, we are ready to use Stakpak🥳
{% endstep %}

{% step %}

### Hybrid providers (e.g., Google and Anthropic)

Choose "Hybrid Providers" then press enter

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FX2OqM8wPjLhCG797tKOO%2Fimage.png?alt=media&#x26;token=eea212a9-09f0-4c13-8610-cd20b05a9147" alt=""><figcaption></figcaption></figure>

#### Hybrid Mode (mix providers for smart/eco models)

{% hint style="info" %}
You’ll set up a **Smart** model for complex tasks and an **Eco** model for cheaper, lightweight tasks. if you want to use a single model for both skip to the "Single Model Mode" Section
{% endhint %}

1. Choose your preferred provider for the smart mode

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FtO4Mekm7LjYqYH0RTZnE%2Fimage.png?alt=media&#x26;token=6509ff42-7f5d-4f98-90f4-464fa76f8865" alt=""><figcaption></figcaption></figure>

3. Then choose your preferred provider model for the smart mode

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FUgCuNwbs2T4D9dVl4Qsz%2Fimage.png?alt=media&#x26;token=f160ca01-0ede-4f7d-adcc-b6021b032061" alt=""><figcaption></figcaption></figure>

4. Paste your provider's API Key and press enter

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FvoSYiTo90QD1Y1Nwnl6Y%2Fimage.png?alt=media&#x26;token=bb5449c8-9d05-4d8a-baab-e32c3f647f79" alt=""><figcaption></figcaption></figure>

5. Then follow the same steps again to pick the provider, model, and key for your **Eco** mode.
6. Then press "Y" to save your configs

That's it, we are ready to use Stakpak🥳
{% endstep %}

{% step %}

### Bring Your Own Model

Choose "Bring Your Own Model" then press enter

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FtKq2PECkFQyAsXvE8n2C%2Fimage.png?alt=media&#x26;token=929f9faa-3ebc-4be8-b072-fd714d442024" alt=""><figcaption></figcaption></figure>

1. Enter your OpenAI compatible chat completion API endpoint
   1. Example: <https://api.openai.com/v1/chat/completions>
2. Write a name for your model
3. Enter API key if needed

That's it, we are ready to use Stakpak🥳
{% endstep %}
{% endstepper %}

## Configuration sample&#x20;

To view the Configuration sample open the terminal and type `stakpak config sample`

```markdown
# Stakpak Configuration File

# Profile-based configuration allows different settings for different environments
[profiles]

# Special 'all' profile - settings that apply to ALL profiles as defaults
# Individual profiles can override these settings
[profiles.all]
api_endpoint = "https://apiv2.stakpak.dev"
# Common tools that should be available across all profiles
allowed_tools = ["view", "search_docs", "read_rulebook", "local_code_search"]
# Conservative auto-approve list that works for all environments
auto_approve = ["view", "search_docs", "read_rulebook"]

[profiles.all.rulebooks]
# Common rulebook patterns for all profiles
include = ["stakpak://yourdomain.com/common/**"]
exclude = ["stakpak://yourdomain.com/archive/**"]
include_tags = ["common", "shared"]
exclude_tags = ["archived", "obsolete"]

# Default profile - used when no specific profile is selected
# Inherits from 'all' profile and can override specific settings
[profiles.default]
api_key = "your_api_key_here"

# Extends the 'all' profile's allowed_tools with additional development tools
allowed_tools = ["view", "search_docs", "read_rulebook", "local_code_search", "create", "str_replace", "run_command"]

# Inherits auto_approve from 'all' profile (view, search_docs, read_rulebook)
# No need to redefine unless you want to override

# Rulebook filtering configuration
[profiles.default.rulebooks]
# URI patterns to include (supports glob patterns like * and **)
include = ["stakpak://yourdomain.com/*", "stakpak://**/*.md"]

# URI patterns to exclude (supports glob patterns)
exclude = ["stakpak://restricted.domain.com/**"]

# Tags to include - only rulebooks with these tags will be loaded
include_tags = ["terraform", "kubernetes", "security"]

# Tags to exclude - rulebooks with these tags will be filtered out
exclude_tags = ["deprecated", "experimental"]

# Production profile - stricter settings for production environments
# Inherits from 'all' profile but restricts tools for safety
[profiles.production]
api_key = "prod_api_key_here"

# Restricts allowed_tools to only read-only operations (overrides 'all' profile)
allowed_tools = ["view", "search_docs", "read_rulebook"]

# Uses the same conservative auto_approve list from 'all' profile
# No need to redefine since 'all' profile already has safe defaults

[profiles.production.rulebooks]
# Only include production-ready rulebooks
include = ["stakpak://yourdomain.com/prod/**"]
exclude = ["stakpak://yourdomain.com/dev/**", "stakpak://yourdomain.com/test/**"]
include_tags = ["production", "stable"]
exclude_tags = ["dev", "test", "experimental"]

# Development profile - more permissive settings for development
# Inherits from 'all' profile and extends with development-specific tools
[profiles.development]
api_key = "dev_api_key_here"

# Extends 'all' profile's allowed_tools with write operations for development
allowed_tools = ["view", "search_docs", "read_rulebook", "local_code_search", "create", "str_replace", "run_command"]

# Extends 'all' profile's auto_approve with additional development tools
auto_approve = ["view", "search_docs", "read_rulebook", "create"]

[profiles.development.rulebooks]
# Include development and test rulebooks
include = ["stakpak://yourdomain.com/dev/**", "stakpak://yourdomain.com/test/**"]
exclude = []
include_tags = ["dev", "test", "experimental"]
exclude_tags = []

# Global settings that apply to all profiles
[settings]
# Machine name for device identification
machine_name = "my-development-machine"

# Automatically append .stakpak to .gitignore files
auto_append_gitignore = true
```