Getting Started

Get Hoist running and create your first feature flag in under 5 minutes.

Prerequisites

• Docker and Docker Compose (recommended)
• Or: Go 1.25+, PostgreSQL 15+, Redis 7+

Quick Start with Docker

1. Start Hoist

# Clone the repository
git clone https://git.macco.dev/macco/hoist.git
cd hoist

# Start all services
docker compose up -d

This starts:

• Hoist API server on port 4340
• PostgreSQL database on port 5432
• Redis cache on port 6379

2. Open the Dashboard

Navigate to http://localhost:4340 and create your account.

3. Create Your First Flag

1. Create an organization - Organizations group your projects
2. Create a project - Projects contain your feature flags
3. Create a flag - Click "New Flag" and configure:
   • Key: new-checkout-flow (unique identifier)
   • Type: Boolean
   • Default value: false

4. Get an API Key

1. Go to Settings > API Keys
2. Click Create API Key
3. Select Server Key for backend usage
4. Copy the key (starts with hoist_live_ or hoist_test_)

5. Install an SDK

Go:

go get git.macco.dev/macco/hoist/sdks/go/hoist

TypeScript:

npm install @hoist/sdk

6. Evaluate Your Flag

Go:

package main

import (
    "context"
    "fmt"
    "log"

    "git.macco.dev/macco/hoist/sdks/go/hoist"
)

func main() {
    client, err := hoist.NewClient(hoist.Config{
        APIKey:  "hoist_live_xxx", // Your API key
        BaseURL: "http://localhost:4340",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()

    // Evaluate a boolean flag
    enabled, err := client.Bool(ctx, "new-checkout-flow", false, hoist.Context{
        TargetingKey: "user-123",
        Attributes: map[string]any{
            "plan": "pro",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    if enabled {
        fmt.Println("New checkout flow is enabled!")
    } else {
        fmt.Println("Using classic checkout flow")
    }
}

TypeScript:

import { HoistClient } from '@hoist/sdk'

const client = new HoistClient({
  apiKey: 'hoist_live_xxx', // Your API key
  baseURL: 'http://localhost:4340',
})

await client.waitForInitialization()

const enabled = await client.booleanValue('new-checkout-flow', false, {
  targetingKey: 'user-123',
  attributes: { plan: 'pro' },
})

if (enabled) {
  console.log('New checkout flow is enabled!')
} else {
  console.log('Using classic checkout flow')
}

client.close()

7. Toggle Your Flag

Go back to the dashboard, find your flag, and toggle it on. With streaming enabled, your SDK will receive the update in real-time!

Next Steps

• Installation - Production deployment options
• Configuration - Environment variables and config file
• Core Concepts - Understand organizations, projects, and targeting
• Go SDK - Complete Go SDK documentation
• TypeScript SDK - Complete TypeScript SDK documentation

Troubleshooting

Cannot connect to database

Ensure PostgreSQL is running and the connection details match your configuration:

docker compose logs postgres

Cannot connect to Redis

Ensure Redis is running:

docker compose logs redis

SDK not receiving updates

1. Verify your API key is valid
2. Check the API server logs for connection errors
3. Ensure WebSocket connections are not blocked by a proxy

Dashboard shows blank page

Clear your browser cache and ensure the API server is running:

curl http://localhost:4340/api/v1/health