Skip to main content

​
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

~/Library/Application Support/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

Workspace files use restrictive permissions:
# macOS/Linux
chmod 700 ~/Library/Application Support/Auk/
chmod 600 ~/Library/Application Support/Auk/workspaces/*/settings.json
Environment variables marked as “secret”:
  • Not displayed in UI by default
  • Can be encrypted at rest (coming soon)
  • Excluded from Git commits (if configured)
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

# 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 ~/

​
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:
OSMax Files per DirectoryMax File Size
macOS (APFS)Unlimited8 EB
Windows (NTFS)4,294,967,29516 EB
Linux (ext4)Unlimited16 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:
  1. Auto-Recovery - Auk attempts automatic recovery
  2. Backup Restore - Restore from local backup
  3. Git Restore - Restore from Git history
  4. 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