Data Storage - Auk Documentation

Local-First Architecture

Auk stores all data on your local file system, giving you complete control and ownership of your API collections, environments, and history.

File System Storage

All data stored as JSON files on your local disk

No Cloud Dependency

Works completely offline, no internet required

Full Control

You own and control all your data

Git-Friendly

Plain text JSON files work perfectly with Git

Storage Location

Default Locations

macOS
Windows
Linux

~/Library/Application Support/Auk/workspaces/

Or custom location:

~/Documents/Auk/
~/Projects/api-collections/

C:\Users\YourName\AppData\Roaming\Auk\workspaces\

Or custom location:

C:\Users\YourName\Documents\Auk\
D:\Projects\api-collections\

~/.config/Auk/workspaces/

Or custom location:

~/Documents/Auk/
~/projects/api-collections/

Data Structure

Workspace Directory

workspace-name/
├── collections/              # API collections
│   ├── my-api.json
│   └── another-api.json
├── environments/             # Environment variables
│   ├── development.json
│   ├── staging.json
│   └── production.json
├── history/                  # Request history
│   └── 2024-02.json
├── settings.json            # Workspace settings
├── .git/                    # Git repository (optional)
└── .gitignore              # Git ignore rules

Collection File Format

Collections are stored as JSON files:

{
  "v": 1,
  "name": "My API Collection",
  "folders": [
    {
      "name": "Authentication",
      "requests": [
        {
          "name": "Login",
          "method": "POST",
          "endpoint": "{{baseUrl}}/auth/login",
          "headers": [],
          "body": {
            "contentType": "application/json",
            "body": "{\"email\":\"[email protected]\"}"
          }
        }
      ]
    }
  ]
}

Environment File Format

Environments are stored as JSON files:

{
  "name": "Development",
  "variables": [
    {
      "key": "baseUrl",
      "value": "http://localhost:3000",
      "secret": false
    },
    {
      "key": "apiKey",
      "value": "dev-key-123",
      "secret": true
    }
  ]
}

Data Persistence

Automatic Saving

Auk automatically saves changes:

Immediate - Changes saved instantly to disk
Atomic - File writes are atomic to prevent corruption
Locked - File locking prevents concurrent write conflicts

File Watching

Auk monitors file changes:

Detects external modifications
Reloads data automatically
Prompts for conflict resolution if needed

Data Security

Local Security

File Permissions

Workspace files use restrictive permissions:

# macOS/Linux
chmod 700 ~/Library/Application Support/Auk/
chmod 600 ~/Library/Application Support/Auk/workspaces/*/settings.json

Secret Variables

Environment variables marked as “secret”:

Not displayed in UI by default
Can be encrypted at rest (coming soon)
Excluded from Git commits (if configured)

Disk Encryption

Use OS-level encryption:

macOS: FileVault
Windows: BitLocker
Linux: LUKS

Git Security

When using Git sync:

# .gitignore template
*.secret.json
.env
.env.local
secrets/
*.key
*.pem

Data Migration

Export Data

Export workspace data:

# Entire workspace
cp -r ~/Library/Application Support/Auk/workspaces/my-workspace ~/backup/

# Specific collection
cp ~/Library/Application Support/Auk/workspaces/my-workspace/collections/api.json ~/backup/

Import Data

Import from other tools:

Postman - Import Postman collections (v2.1)
Insomnia - Import Insomnia exports
OpenAPI - Import OpenAPI/Swagger specs
Auk - Import Auk collections

Backup Strategies

Local Backup

Manual Backup
Time Machine (macOS)
Automated Script

# Create backup
tar -czf auk-backup-$(date +%Y%m%d).tar.gz \
  ~/Library/Application Support/Auk/workspaces/

# Restore backup
tar -xzf auk-backup-20240220.tar.gz -C ~/

# Time Machine automatically backs up:
~/Library/Application Support/Auk/

# Restore from Time Machine:
# 1. Open Time Machine
# 2. Navigate to Auk folder
# 3. Select date and restore

#!/bin/bash
# backup-auk.sh

BACKUP_DIR=~/Backups/Auk
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/auk-$DATE.tar.gz \
  ~/Library/Application Support/Auk/workspaces/

# Keep only last 30 days
find $BACKUP_DIR -name "auk-*.tar.gz" -mtime +30 -delete

Git Backup

Using Git provides automatic backup:

# Every sync creates a backup on remote
git push origin main

# View history
git log --oneline

# Restore from any point
git checkout <commit-hash>

Performance Considerations

Large Collections

For workspaces with many collections:

Lazy Loading - Collections loaded on demand
Indexing - Fast search across collections
Pagination - History paginated by month

File System Limits

Be aware of file system limitations:

OS	Max Files per Directory	Max File Size
macOS (APFS)	Unlimited	8 EB
Windows (NTFS)	4,294,967,295	16 EB
Linux (ext4)	Unlimited	16 TB

Data Integrity

Corruption Prevention

Auk prevents data corruption:

Atomic Writes - Files written atomically
Validation - JSON schema validation
Checksums - File integrity checks
Backups - Automatic backup before writes

Recovery

If data corruption occurs:

Auto-Recovery - Auk attempts automatic recovery
Backup Restore - Restore from local backup
Git Restore - Restore from Git history
Manual Edit - Edit JSON files directly

Next Steps

File System Storage

Deep dive into file system storage

Data Location

Find and manage your data files

Backup & Restore

Learn backup and recovery strategies

Git Sync

Use Git for backup and collaboration

​Local-First Architecture

File System Storage

No Cloud Dependency

Full Control

Git-Friendly

​Storage Location

​Default Locations

​Data Structure

​Workspace Directory

​Collection File Format

​Environment File Format

​Data Persistence

​Automatic Saving

​File Watching

​Data Security

​Local Security

​Git Security

​Data Migration

​Export Data

​Import Data

​Backup Strategies

​Local Backup

​Git Backup

​Performance Considerations

​Large Collections

​File System Limits

​Data Integrity

​Corruption Prevention

​Recovery

​Next Steps

File System Storage

Data Location

Backup & Restore

Git Sync

Local-First Architecture

Storage Location

Default Locations

Data Structure

Workspace Directory

Collection File Format

Environment File Format

Data Persistence

Automatic Saving

File Watching

Data Security

Local Security

Git Security

Data Migration

Export Data

Import Data

Backup Strategies

Local Backup

Git Backup

Performance Considerations

Large Collections

File System Limits

Data Integrity

Corruption Prevention

Recovery

Next Steps