Getting Started with Upland Hub

This guide walks you through setting up the Upland Hub platform from scratch, running your first agent, and understanding the dashboard.

Prerequisites

Before you begin, install the following:

Tool	Purpose	Install
Bun (v1.1+)	JavaScript runtime and package manager	`curl -fsSL https://bun.sh/install \| bash`
Wrangler (v3+)	Cloudflare Workers CLI	Comes bundled via `bunx wrangler`
Git	Version control	`brew install git` (macOS)
Node.js (v20+)	Required by some Wrangler internals	`brew install node`

Optional (for production deployment):

Cloudflare account (free tier works for dev)
Claude API key from Anthropic (for AI generation)
fal.ai API key (for image/video generation)

First-Time Setup

1. Clone the repository

git clone https://github.com/pnwcoug253/upland-hub.git ~/projects/upland-hub
cd ~/projects/upland-hub

2. Install dependencies

bun install

This installs dependencies for both the api/ and dashboard/ workspaces.

3. Configure API keys

Create the local environment file for the API:

cat > api/.dev.vars << 'EOF'
CLAUDE_API_KEY=sk-ant-your-key-here
# Optional keys (platform works without these):
# FAL_API_KEY=your-fal-key
# RESEND_API_KEY=re-your-resend-key
# META_APP_ID=your-meta-app-id
# META_APP_SECRET=your-meta-app-secret
# GOOGLE_CLIENT_ID=your-google-client-id
# GOOGLE_CLIENT_SECRET=your-google-client-secret
# STRIPE_SECRET_KEY=sk_test_your-key
# STRIPE_WEBHOOK_SECRET=whsec_your-secret
EOF

Minimum to get started: Just the CLAUDE_API_KEY. Without it, the platform falls back to the free Cloudflare Workers AI (Llama 3.3), which works but produces lower-quality content.

4. Initialize the database

cd ~/projects/upland-hub/api
bunx wrangler d1 execute upland-db --local --file=./migrations/latest.sql
bunx wrangler d1 execute upland-db --local --file=./seeds/seed.sql

This creates:

12 database tables
21 agent template definitions
The Upland agency organization (your org)
Two seed clients: The Hop Thief (bar, Walla Walla) and Revelry Vintners (winery)
A dev admin user

5. Start the servers

Open two terminal windows:

Terminal 1 -- API server:

cd ~/projects/upland-hub/api && bunx wrangler dev --port 8788

Terminal 2 -- Dashboard:

cd ~/projects/upland-hub/dashboard && bun run dev

The dashboard runs at http://localhost:5174 and the API at http://localhost:8788.

Port note: Upland Hub uses ports 8788/5174 to avoid conflicts with BuildZero (8787/5173).

Step 1: Log in

Open http://localhost:5174 in your browser.
On the login page, click the "Dev Login" button (only available in development mode).
This creates or finds a super_admin user and logs you in immediately. No email/password needed during development.

Step 2: Navigate the dashboard

After logging in, you land on the Agency Dashboard. The sidebar shows:

Dashboard -- KPI cards, recent runs, credit usage per client
Clients -- All client organizations with search
Agent Studio -- Where you trigger AI agents
Review Queue -- Content waiting for approval
Calendar -- Month grid of scheduled/published content
Media -- Gallery of generated images and videos
Analytics -- Charts on runs, content, and credits
Plans -- Plan breakdown and agent access matrix
Settings -- Profile, API key info, notification preferences

Step 3: Run your first agent

Click Agent Studio in the sidebar.
You will see agents grouped by category (Content, Strategy, SEO, etc.).
Select Social Post Generator.
Choose a client from the dropdown (e.g., "The Hop Thief").
Fill in the input fields:
- Topic: "Happy hour specials this Friday"
- Platforms: Instagram, Facebook
- Mood: Casual and inviting
Click Run Agent.
A toast notification appears with a link to view the run.

Step 4: Review the output

Go to the Review Queue (or click the toast link).
You will see the generated content with the client name and agent type.
Click View Details to see the full output, including:
- Generated captions for each platform
- Hashtag suggestions
- Image generation prompts (actual images if FAL_API_KEY is set)
Click Approve to move it to the publish queue, or Reject with notes.

Step 5: Check the content calendar

Go to Calendar.
Approved content appears on the calendar. You can schedule it for specific dates by editing the content item.

Understanding the Dashboard

Agency vs. Client Views

The dashboard has two modes based on user role:

Role	View	What they see
`super_admin`	Agency	Everything -- all clients, all agents, full review queue
`agency_operator`	Agency	Same as super_admin
`client_admin`	Client Portal	Their own content, brand kit, reports, approvals
`client_viewer`	Client Portal	Read-only view of their content and reports

Key Concepts

Organizations -- Every entity is scoped to an org. Upland is the "agency" org. Each client is a separate org. This is how multi-tenancy works.

Agent Configs -- Each agent can be enabled/disabled per client org. You can also set:

Review mode: auto_publish, agency_review, client_review, or dual_review
Schedule: Cron expression for automated runs
Model override: Force a specific AI model
Custom instructions: Extra context appended to the agent's prompt

Credit System -- Every agent run costs credits. Each plan includes a monthly allocation that resets automatically. The credits ledger tracks every deduction.

Brand Kit -- Structured client data (voice, products, colors, competitors, USPs) that gets injected into every agent's prompt. This is what makes the AI output specific to each client.

Adding Your First Real Client

From the Dashboard

Go to Clients and click Add Client (or go to the Client Onboarding page).
The 6-step onboarding wizard walks you through:
- Step 1: Business info (name, type, location, vertical)
- Step 2: Plan selection
- Step 3: Brand voice and personality
- Step 4: Products, services, and USPs
- Step 5: Visual identity (colors, logo)
- Step 6: Platform preferences and review mode
This creates the client org, brand kit, and default agent configs.

Via API (for automation)

# 1. Get your access token
TOKEN=$(curl -s http://localhost:8788/api/auth/dev-login -X POST | jq -r '.data.access_token')

# 2. Create the org
curl -X POST http://localhost:8788/api/orgs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "River City Coffee",
    "plan": "starter",
    "vertical": "coffee"
  }'

# 3. Set up their brand kit (use the org_id from the response)
curl -X PUT http://localhost:8788/api/brand-kits/ORG_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "River City Coffee",
    "industry": "Coffee Shop",
    "vertical": "coffee",
    "location_city": "Kennewick",
    "location_state": "WA",
    "voice_description": "Warm, community-focused, passionate about craft coffee",
    "target_audience": "Coffee enthusiasts and remote workers in Tri-Cities",
    "content_pillars": ["craft coffee education", "community events", "behind the roast"]
  }'

After Onboarding

Once the client org and brand kit exist:

Enable the agents you want for this client (Agent Studio > select client > toggle agents)
Set review modes per agent (most clients start with agency_review)
Run a Content Calendar agent to plan the first month
Run Social Post agents to generate the first batch of content
Review and approve in the Review Queue
Content flows to the publish queue (auto-posts when platform connections are set up)

Common Commands Reference

# Start API
cd ~/projects/upland-hub/api && bunx wrangler dev --port 8788

# Start Dashboard
cd ~/projects/upland-hub/dashboard && bun run dev

# Reset database (wipes all data)
cd ~/projects/upland-hub/api
bunx wrangler d1 execute upland-db --local --file=./migrations/latest.sql
bunx wrangler d1 execute upland-db --local --file=./seeds/seed.sql

# Typecheck everything
cd ~/projects/upland-hub && bun run typecheck:api && bun run typecheck:dashboard

# Build dashboard for production
cd ~/projects/upland-hub/dashboard && bun run build

Troubleshooting

"Agent run failed" with no useful error

Check the API terminal output. Common causes:

Missing CLAUDE_API_KEY in api/.dev.vars (falls back to Workers AI, which may not be available locally)
Client org has 0 credits remaining
Agent is not enabled for the selected client org

"Dashboard shows blank page"

Make sure the API server is running on port 8788
Check the browser console for errors
Verify the Vite proxy config in dashboard/vite.config.ts points to :8788

"Database errors after pulling new code"

Re-run migrations:

cd ~/projects/upland-hub/api
bunx wrangler d1 execute upland-db --local --file=./migrations/latest.sql
bunx wrangler d1 execute upland-db --local --file=./seeds/seed.sql

"Content not appearing after approval"

Content goes to the publish queue, which requires platform connections (Meta OAuth, Google Business Profile). Without connections, content stays in "approved" status -- you can still see it in the calendar and content list.