DIY Installation Instructions

Step 1.2 Create a VPS

These instructions explain how to create a virtual private server (VPS) for simple testing of the Luca system while it is in beta. We're focusing on giving you the easiest option at the lowest cost — but if you want to use it in production you may want to upgrade to a faster server with backups and management in place.

1. Go to the Liquid Web referral link cart.liquidweb.com/refer-a-friend/574405721575 — you should see this page:

   

2. Create Your VPS. Click the "Explore VPS" button under Managed VPS Hosting, then switch the option at the top of the page from managed to self-managed — this reduces the prices shown. Make sure Linux is selected above the list and click Buy now on the cheapest option.

3. In the configuration form, choose the location closest to you, leave management on self-managed for a test server (or choose a management option for professional use), and select Ubuntu 24.04 LTS in the software section. You do not need a control panel. Even the smallest specification server is fine for testing. Backups and extras are optional but recommended for production use.

4. Choose monthly, yearly or 2-year billing, click Add to cart, and complete the checkout to create your account and make payment.

5. Once payment is complete you should be redirected to the Liquid Web user portal. If not, go to portal.liquidweb.com. Choose My Servers from the left-hand menu and click the listing for your new server to open the server details page.

6. Wait 1–2 minutes for the server to be fully provisioned — you'll know it's ready when you see a green tick and the word Running below the server name:

   

7. Note the server's public IP address — you will need it in the next step.

Step 1.3 Point your domain at the server

Luca requires HTTPS and a valid domain. The automated installer handles the SSL certificate, but your domain must be pointing at the server IP first.

1. Log into your domain registrar's DNS control panel.

2. Create an A record pointing your chosen subdomain (e.g. accounts.yourbusiness.com) to the server's IP address. TTL of 300 seconds is fine.

3. Wait 5–15 minutes for DNS to propagate. Verify with:

# Run this on your computer
nslookup accounts.yourbusiness.com

4. Once the IP returned matches your server IP, proceed to Part 2.

Step 1.4 Connect via SSH

Open a terminal (macOS/Linux) or PowerShell / Windows Terminal (Windows) and connect:

ssh root@<your-server-ip>

Use the primary IP shown on the server details page, along with the username and password shown below it under Server Credentials, to log in over SSH.

Step 2.1 Run the one-command installer

From your SSH session on the server:

curl -sSL https://raw.githubusercontent.com/roger296/luca-general-ledger/main/install.sh \
  -o /tmp/luca-install.sh && sudo bash /tmp/luca-install.sh

The script downloads first and then runs — this is intentional. Piping directly to bash would prevent interactive prompts from working on all systems.

Step 2.2 Answer the installer prompts

Step 2.3 Verify the installation

# Check containers are running — all should show "Up"
docker compose ps

# Check the GL API is responding
curl -s https://your-domain/api/health | python3 -m json.tool

You should receive {"status": "ok"}. Open https://your-domain in your browser — you should see the Luca login page. Sign in with your admin credentials.

Step 3.1 Subscribe to Claude Co-Work Pro

1. Go to claude.ai and sign up or sign in to your Anthropic account.

2. Upgrade to the Pro plan (from $20/month). This is billed directly by Anthropic and is separate from any Luca hosting costs.

3. Note your Anthropic account email — you will use it to sign in to the Claude desktop app.

Step 3.2 Download and install the Claude desktop app

1. Visit claude.ai/download and download the installer for your OS.

2. macOS: Open the .dmg and drag Claude to your Applications folder.

3. Windows: Run the installer and follow the on-screen steps.

4. Launch the Claude app and sign in with your Anthropic account.

5. Confirm your Pro subscription is active — you should see "Pro" in the account menu.

Step 4.1 Create a Co-Work workspace folder

Create a new folder on your computer for your Luca workspace. You can do this through File Manager (Windows) or Finder (Mac), or use the command line:

# macOS / Linux
mkdir -p ~/LucaWorkspace

# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:USERPROFILE\LucaWorkspace"

In the Claude desktop app, open Co-Work mode and select this folder as your workspace when prompted (or via Settings → Co-Work → Workspace Folder → Browse).

Step 4.2 Download the skill files from GitHub

You can either clone the repository or download a ZIP. Point your browser to github.com/roger296/lucaV0.5 to access the repo.

Option A — Clone the full repository (recommended):

cd ~/LucaWorkspace
git clone https://github.com/roger296/lucaV0.5.git luca-source

Option B — Download ZIP: Click the green Code button on the GitHub page → Download ZIP, then extract it and note the location.

Step 4.3 Copy skills into your workspace

# macOS / Linux
mkdir -p ~/LucaWorkspace/.claude/skills
cp -r ~/LucaWorkspace/luca-source/skills/lucas-general-ledger \
    ~/LucaWorkspace/.claude/skills/
cp -r ~/LucaWorkspace/luca-source/skills/luca-setup \
    ~/LucaWorkspace/.claude/skills/

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\LucaWorkspace\.claude\skills"
Copy-Item -Recurse "luca-source\skills\lucas-general-ledger" `
    "$env:USERPROFILE\LucaWorkspace\.claude\skills\"
Copy-Item -Recurse "luca-source\skills\luca-setup" `
    "$env:USERPROFILE\LucaWorkspace\.claude\skills\"

Fully quit and relaunch the Claude desktop app so it picks up the new skills.

Step 5.1 Generate Co-Work credentials on your server

1. Open https://your-domain and sign in with your admin credentials.

2. Navigate to Admin → Co-Work Credentials in the sidebar.

3. Click + Generate credentials.

4. You receive three values: the MCP Server URL (https://your-domain/mcp), a Client ID, and a Client Secret.

Step 5.2 Add the connector in Claude Co-Work

1. Open the Claude desktop app.

2. Go to Settings → Customize → Connectors → Add connector.

3. Fill in the form:

4. Click Connect. Your browser will open the Luca login page for OAuth authorisation.

5. Sign in with your Luca admin credentials and click Authorise.

6. Return to the Claude app. The connector should show as Connected with a green indicator.

Step 5.3 Verify the MCP connection

In a Co-Work session in your workspace, type:

How many MCP tools do you have access to?

Claude should report access to 50 Luca MCP tools. If it reports zero, see the troubleshooting section below.

Step 6.1 Wake Luca

In a Co-Work session in your workspace, type:

Wake Luca

Claude will load the lucas-general-ledger skill and confirm Luca is active and connected to your General Ledger, with a summary of your current ledger state.

Step 6.2 Review your Chart of Accounts

Show me the current Chart of Accounts

Luca ships with a UK SME default Chart of Accounts. Customise it conversationally:

Add a new expense account called "AWS Infrastructure" under code 7200
Rename account 4000 to "Online Sales Revenue"

Step 6.3 Example commands to explore

Financial reports:

Show me the Profit and Loss for this month
What is the current balance sheet?
Who are my top 5 overdue debtors?
What is our VAT position for Q1?

Posting transactions:

Post a purchase invoice from Acme Ltd for £450 + VAT, dated today, for office supplies
Record a payment received from Johnson & Co for £2,340 against invoice INV-0042
Post a bank transfer of £5,000 from current account to savings account

Bank reconciliation:

Start a bank reconciliation for the current account
Import this bank statement and match any transactions you can

Step 7.1 Create your document inbox folder

# macOS / Linux
mkdir -p ~/LucaWorkspace/inbox
mkdir -p ~/LucaWorkspace/inbox/processed

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\LucaWorkspace\inbox"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\LucaWorkspace\inbox\processed"

Drop documents into inbox/. Luca moves them to inbox/processed/ after handling them.

Step 7.2 Process documents manually

Process all documents in my inbox

# Or with a specific file attached or referenced:
Post this invoice to the ledger

The gl-document-posting skill activates automatically, reads each document, identifies the type, extracts key fields, determines the correct accounting treatment, and posts the journal entry.

Step 7.3 Set up a nightly scheduled batch task

For fully automated daily processing, set up a scheduled task in Claude Co-Work. In a Co-Work session:

Set up a scheduled task for Luca's nightly batch processing

Claude will guide you through the setup. Specify:

• Schedule: Daily at 02:00 (runs while you sleep)
• Task: Run Luca's nightly batch — reconcile bank feeds, process inbox documents, prepare VAT data, generate exception report
• Workspace: Your LucaWorkspace folder

Trigger a test run immediately to verify:

Run the Luca batch now

Step 7.4 Morning briefing

Once the nightly batch has run, ask Luca for a briefing:

Wake Luca
Give me a morning briefing

Luca will summarise what happened overnight, what was reconciled automatically, and what needs your attention today — a CFO-level view of your financial position in under a minute.

MCP connector shows "Not Connected"

• SSH to the server and run docker compose ps — all services should show "Up".
• Test the endpoint directly: curl https://your-domain/mcp should return a JSON-RPC response.
• Rebuild the containers: docker compose up -d --build
• In Claude, disconnect and reconnect the connector — the OAuth token may have expired.

"Invalid client" error during OAuth

• Regenerate credentials: Admin → Co-Work Credentials → + Generate credentials.
• Re-enter the new Client ID and Client Secret in Claude's connector settings.

Skills not appearing in Co-Work

• Skills must be at .claude/skills/ inside your workspace root — not in a sub-subfolder.
• Fully quit and relaunch the Claude desktop app after copying skills.
• Type: "What skills do you have?" — the skills must appear in the list to be active.

Installer fails at SSL certificate step

• DNS has not propagated yet. Run nslookup your-domain and confirm it returns your server IP.
• Port 80 must be open on the server for the Let's Encrypt HTTP-01 challenge. Check Liquid Web firewall settings.
• Re-run the installer: sudo bash /tmp/luca-install.sh