DIY Installation Instructions

Step 1.1 Create your Liquid Web account

1. Go to cart.liquidweb.com/refer-a-friend/574405721575 and click Sign Up. Using this referral link gives us a small commission at no cost to you — it directly funds Luca development.

2. Complete registration and verify your email address.

3. Add a payment method. Liquid Web accepts card and PayPal.

Step 1.2 Create a VPS

From your Liquid Web control panel, click Create server and choose the following configuration:

1. Set a strong root password or, better, add your SSH public key for keyless authentication.

2. Click Create and wait 1–2 minutes for the server to boot.

3. Note the server's public IP address — you will need it for DNS.

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

Step 1.4 Connect via SSH

ssh root@<your-server-ip>

Accept the host key fingerprint when prompted. You should now see a root shell.

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 ($20/month). This is billed directly by Anthropic and is separate from any Luca hosting costs.

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

# 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

Clone the Luca repository into your workspace:

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

Alternatively, go to github.com/roger296/lucaV0.5, click the green Code button → Download ZIP, and extract it.

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

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 summarises what happened overnight, what was reconciled automatically, and what needs your attention — 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