Getting started with Scarif One

Reading time: 25 minutes. Hands-on time: 45 minutes. What you'll have at the end: a running Scarif One instance, your brand voice configured, your store connected, and one ad creative generated and ready to publish.

No prior experience with Docker, APIs, or AI tools required. Anything that uses jargon explains the jargon first.

Before you start

You need three things in front of you:

1. A computer that stays on. A Mac mini, an old laptop you leave plugged in, or a Linux VPS. If you switch off the computer, Scarif One switches off too. Most customers run it on a Mac mini in a cupboard for £15/month of electricity.
2. A Google account. You'll get a free Gemini API key from this. Gemini is the AI brain that writes your ad copy and generates your images. The free tier is generous — you'll hit hundreds of generations a month at zero cost.
3. One product photo. Just one to start. PNG or JPG. Doesn't have to be perfect — we'll generate variations from it.

That's it. You don't need a Shopify store yet (you can connect one later), you don't need a Meta ad account (also later), you don't even need a website. We'll build out from whatever you have.

The 10-minute decision: hosted or self-host?

Recommendation: start with the hosted 14-day trial unless you already know why you want self-host. You can migrate from hosted to self-host later (we have an export tool that ships your tenant data as a Docker volume).

This tutorial covers both paths. Pick yours and follow the relevant section.

Path A — Hosted (5 minutes)

Step A1: Create your account

1. Open https://scarifone.com in any browser.
2. Click Start free 14-day trial in the top-right.
3. You'll see a form with three fields:
   • Email — this becomes your login. Use one you actually check.
   • Business name — what your customers know you as. Don't use a legal entity name unless that's what's on your storefront.
   • Subdomain — this is the URL you'll log into forever. If your business is "Acme Coffee" type acme and your URL becomes acme.scarifone.com. Lowercase letters and dashes only.
4. Click Continue to checkout.
5. Stripe Checkout opens. You'll see "£0 for 14 days, then £49/month". Enter your card details. You won't be charged today. The card is on file so the trial converts seamlessly if you don't cancel — and you can cancel any time during the trial with one click.
6. After checkout, you'll be redirected to https://yoursubdomain.scarifone.com/login.

Step A2: First login

1. Check your email for a magic-link. It arrives within 30 seconds. Subject: "Your Scarif One login link."
2. Click the link. It logs you in directly — no password to remember.
3. You land on /setup. Skip ahead to Part 2 — your brand profile below.

Didn't get the email? Check spam. If still missing, our system prefers a Resend-validated From address — if you self-hosted you'd configure it; on hosted we handle it. Email support@scarifone.com and we'll send a manual link.

Path B — Self-host (15 minutes)

Step B1: Install Docker

Docker is the program that runs Scarif One in an isolated container so it doesn't conflict with anything else on your computer.

On a Mac: download Docker Desktop from https://www.docker.com/products/docker-desktop. Install it. Open it. You'll see a whale icon in your menu bar — that means Docker is running.

On Linux: run curl -fsSL https://get.docker.com | sh and follow the prompts. Then sudo usermod -aG docker $USER and log out + back in.

On Windows: download Docker Desktop, install it, enable WSL 2 when prompted (it's the default).

To check Docker is working, open Terminal (Mac/Linux) or PowerShell (Windows) and run:

docker --version
docker compose version

You should see version numbers for both. If you get "command not found", Docker isn't installed correctly — go back to the install step.

Step B2: Get a Gemini API key (free)

1. Open https://aistudio.google.com/apikey in your browser.
2. Sign in with any Google account.
3. Click Create API key. Pick Create API key in new project if it asks.
4. Copy the key. It looks like AIzaSyA… — about 39 characters long.
5. Paste it somewhere safe (Notes, password manager). Treat it like a password.

What does this key do? Every time Scarif One writes ad copy, generates an image, drafts an email, or replies to a review — it sends a request to Google's Gemini AI using this key. Google bills you (the key owner). The free tier covers most small-business use easily; if you blow past it Google will send you an email and gently throttle.

Step B3: Run the installer

Open Terminal again. Paste this and press Enter:

curl -fsSL https://raw.githubusercontent.com/Scarif-One/scarif-one/main/scripts/install.sh | bash

The installer:

1. Confirms Docker is installed (you've already done that)
2. Creates ~/scarif-one/ as the install directory
3. Downloads docker-compose.yml (the Docker recipe) and .env.example (the config template)
4. Asks you to paste your Gemini key. Paste it from Step B2.
5. Pulls the latest Scarif One image from GitHub Container Registry
6. Starts the container

Total time: ~3 minutes depending on your download speed.

When it's done you'll see:

🚀 Scarif One is running.

  Open:  http://localhost:3000
  Data:  /Users/yourname/scarif-one/data
  Logs:  cd /Users/yourname/scarif-one && docker compose logs -f

Step B4: First-run wizard

1. Open http://localhost:3000 in your browser.
2. The first time you visit, the app sees no brand profile exists and redirects you straight to /setup — the first-run wizard.
3. Walk through the wizard's 5 steps (covered in detail in Part 2 below).
4. The last step asks you to set an admin username + password. Choose a real password — you'll use these on every future login. No "bootstrap code" pattern; you create your own credentials right here.
5. Click Save + activate. The wizard saves the profile, creates your admin account, signs you in automatically, and drops you on the dashboard.

Forgot your password later? Self-host: edit data/tenants/default/auth.json directly (it's a JSON file). The passwordHash field is argon2 — to reset, delete the user object and re-run the /setup wizard from http://localhost:3000/setup (it creates a fresh admin if one's missing).

Part 2 — Your brand profile (5 minutes)

Both Hosted and Self-host paths land here next. This is the most important screen in the whole product — every ad, email, and reply is generated through the lens of what you fill in here.

You're at /setup. You'll see a form with sections.

Section: Identity

Section: Visual identity

The dashboard theme switches to your primary colour the moment you save. If everything turns coffee-brown, that's correct.

Section: Locale

Section: Commerce defaults

Hit Save

You'll see a green toast: Brand profile saved. Your dashboard re-renders in your brand colour. You're now redirected to /onboarding — the 5-stage new-user wizard.

Part 3 — The onboarding wizard (10 minutes)

Five stages. Each one takes 1-3 minutes. You can skip any stage and come back to it later from /setup or /integrations. The wizard remembers what you've done.

Stage 1 of 5 — Welcome (30 seconds)

You'll see a hero card explaining the next 10 minutes. Read it, click Continue.

Stage 2 of 5 — Connect your store (3 minutes)

This is where we pull your products so AI can write product-aware ads.

You'll see two big buttons:

• 🛍 I have a Shopify store — opens the Shopify integration tutorial inline.
• No store yet — skip — you can still generate generic ads. Your "products" become your services or content.

If you click Shopify, you'll see a step-by-step:

1. Sign in to your Shopify admin.
2. Settings → Apps and sales channels → Develop apps → Create an app called "Scarif One."
3. Configure Admin API scopes — tick: read_products, read_product_listings, read_customers, read_orders, read_inventory, write_files.
4. Save → Install app → click Reveal token once (you only see it ONCE — copy immediately).
5. Paste the token + your .myshopify.com domain into the form below.

Click Test connection. Within 5 seconds you'll see:

✅ Connected to "Acme Coffee"

First sync: Acme Coffee · 47 products · 2,341 customers

Click Save + connect. The wizard advances.

Test failed? The error message is verbose on purpose. Common issues:

• "401 Unauthorized" → token is wrong, regenerate in Shopify (Apps → API credentials → Rotate)
• "403 Forbidden on /products" → you forgot to tick read_products scope, edit the app + reinstall
• "Use the .myshopify.com domain" → you pasted your custom domain, use the technical one (e.g. acme.myshopify.com, not acmecoffee.com)

Stage 3 of 5 — Brand voice (4 minutes)

This is the part most customers underestimate, and the one with the biggest payoff. Your brand voice is the master prompt every AI call gets. Get it right and your ads sound like you. Get it wrong and they sound like every other AI-written ad on the internet.

You'll see four paths. Pick one:

Path 1: AI scan (2 min, recommended for established brands) We scrape your website + extract pages with the most distinctive copy. The AI drafts a brand-voice document from what's already there — your tone, your phrases, your worldview. You then edit it.

Click Run AI scan. A progress bar fills as we crawl 5-15 pages. You'll get a markdown document like:

# Acme Coffee brand voice

## Tone
Warm, slightly defiant. Anti-corporate. Values craft over scale.

## Phrases we use
- "Made for the morning person who refuses to compromise"
- "Brewed by humans, not robots"
…

## Phrases we never use
- "Synergy", "leverage", "best-in-class"
- Anything that sounds like a stock photo
…

Edit it. The more specific you get, the better the output. Spend 10 minutes here, save 100 hours later.

Path 2: Paste a doc (1 min, for brands with an existing brand book) If you already have a brand-voice document — paste it in. Markdown or plain text both work.

Path 3: 5-question interview (3 min, for brands without an existing voice) The AI asks you five questions:

1. Describe your customer in one sentence.
2. What do they say to themselves before buying?
3. What three adjectives describe how you sound?
4. What three adjectives would you NEVER want to sound like?
5. Pick a competitor. What do they sound like that you want to be different from?

The AI drafts a brand-voice document from your answers.

Path 4: Write your own (0 min, for brands who know exactly what they want) Empty markdown editor. Type what you want. Save.

Whichever path you pick, the next screen shows your brand-voice document. Edit it. Add specific phrases you use, products you've named, regional dialect words. The AI uses every line of this verbatim.

Click Save brand voice. Wizard advances.

Stage 4 of 5 — Channels (2 minutes)

You'll see four channel cards: Meta, Klaviyo, Judge.me, and a "See all 9" link.

You can skip all of them. You can ship your first ad without any channel connected — we'll generate the assets and you download them as a zip.

But for the typical small-business user, connect one of:

• Meta if you'll publish to Facebook + Instagram
• Klaviyo if you do email marketing
• Judge.me if you collect product reviews

Each card opens the same tutorial-modal pattern as the Shopify step. Step-by-step, copy buttons, real Test button, verbose errors.

Want all 9? Click See all 9 integrations to jump to /integrations. Mailchimp, Google Ads, TikTok, Pinterest, LinkedIn each have full step-by-step tutorials too.

Click Continue when you've connected the ones you'll use today.

Stage 5 of 5 — Generate your first ad (5 minutes)

This is the moment of truth.

You'll see a card with three fields:

Click Generate.

What happens next:

1. The approval gate fires. A pulsing ⏸ widget appears in the bottom-right. The system has paused before spending tokens, asking you to confirm. This happens for every AI-spend action — your costs are visible and gated.
2. Click the widget. You see a card showing:
   • Estimated cost: ~£0.04 (Flash Image + Pro 2.5 copy)
   • What will be generated (1 ad copy, 1 image)
   • Approve / Reject buttons
3. Click Approve. The widget collapses to a green ✓ for 2 seconds.
4. The ad starts generating. You see:
   • Copy first (~3 seconds)
   • Image second (~10-15 seconds)
5. Both land in the gallery on /create/ad-creatives.

You now have your first ad. Look at it. Read the copy. Look at the image. Does it sound like you? Does the image fit your brand?

If yes: keep this energy. The rest of the product is built around scaling this.

If no: edit your brand voice doc. The AI re-reads it on every generation. The fastest way to fix bad outputs is better inputs.

Click Complete onboarding. You're done.

Part 4 — What to do next

You're now at the dashboard (/). You'll see ~30 tiles. Don't try to use all of them today. Here's the order I'd suggest for week 1:

Day 1: Shore up the foundations

• /integrations — connect any remaining channels you'll use. Each takes 2-10 minutes.
• /setup — add 5-10 local landmarks if you're doing place-based ads ("Brighton Pier", "Devil's Dyke", "Royal Pavilion"). Unlocks the landmark backdrop concept type.
• /spend-caps — set per-day and per-month £ ceilings on AI spend. Defaults are conservative (£5/day for free, £25/day for Pro). The system auto-pauses when you hit them. You will not get a surprise bill.

Day 2-3: Generate volume

• /create/ad-creatives — generate 5 more ads across different concept types. Compare what works.
• /create/email — draft a campaign. Pick a product, pick an angle, watch the AI produce subject + preheader + HTML body.
• /products/ad-trends — research what's working in your niche. AI scans your competitors and reports the angles converting right now.

Day 4-7: Connect the loop

• /publish — schedule your generated ads + emails. Multi-channel queue with per-channel preview.
• /analytics — once you publish, performance data flows back here. Per-asset revenue attribution.
• /strategy — every Monday morning, the AI writes you a one-page memo: "Here's what worked last week, here's what to try next."

Permanently: the bug widget

Bottom-right of every page is a 🐛 icon. Use it.

If anything looks weird, breaks, or you don't understand — click 🐛, drag a screenshot in, type one sentence. The AI auto-triages severity and category. We see it within 5 seconds. Most bugs get fixed within 24 hours.

The bug widget is the single most important feature for your relationship with us. Every bug you file gets fixed for every customer at the same time — same software for everyone, no special-casing.

Common stumbling blocks (and the fix)

"My ads sound generic"

Your brand voice doc is too generic. Edit it. Add 5 specific phrases you say in real life, 3 you'd never say, and one paragraph describing how a competitor sounds and why you don't want to sound like them. Re-generate.

"The image doesn't look like my product"

The first generation uses your store catalog photo as a reference. If your catalog photo is bad (poor lighting, white background only), so is the output. Upload better source photos to /brand/assets and re-generate — the system reaches for the highest-quality reference automatically.

"I'm worried about cost"

Open /spend-caps. Set a £5/day cap. The system physically cannot spend more — every AI call is wrapped in a budget check. Open /admin/health to see exactly what's been spent in the last 7 days. Open /settings/quality to verify everything's set to Flash (the cheap model) by default; only one task uses Pro.

"I don't see my Shopify products"

Two possibilities:

1. The integration test passed but the sync hasn't run yet — wait 60 seconds, refresh /products.
2. Scope mismatch — you're missing read_products. Reconnect from /integrations.

"The approval gate is too aggressive"

Open /approvals. There's a per-feature toggle: text generations can auto-approve, image generations always need approval. Adjust per your tolerance. My recommendation: keep image gens always-approve — that's where 80%+ of your AI cost lives.

"I don't know what to generate"

Open /concierge. It's a 90-second autonomous agent: it reads your brand voice, your top-3 products, your locale, your channels, and proposes the next 7 days of content. You approve, it queues. Best feature for "blank-page paralysis" days.

You've made it

That's the foundation. You have:

• A running install
• A brand voice the AI uses
• A connected store
• One generated ad
• Spend caps to protect you
• A bug widget for everything else

The rest of the product is depth on those primitives. Take it one feature at a time — there's no rush.

Where to next? Read tutorials 02-08 in this folder. Each one covers one major feature in the same depth. They're designed so you can dip in when you're ready for that thing — not all at once.

If anything in this tutorial was unclear, hit the 🐛 widget on any page and tell us. Tutorials get fixed the same way features do.