Install and Configure

Comprehensive setup guide for the AIP SDK with advanced configuration options, security best practices, and troubleshooting tips.

Need the fastest path to a working agent? Jump to the Quick Start first, then return here when you need deeper configuration.

Requirements

• Python 3.10 or higher (3.11+ recommended)

• Operating System: Windows, macOS, or Linux

• Network: Internet access for package installation

Corporate networks may require outbound proxy variables (e.g. HTTP_PROXY/HTTPS_PROXY). Set those before installing or running the CLI if your organisation routes traffic through a proxy.

Install SDK and CLI Together

Installing glaip-sdk provides both the Python SDK and the aip CLI. Pick the install command that matches how you manage dependencies.

pip (Linux/macOS)

pip install --upgrade glaip-sdk

Use when you manage environments with venv or system Python. Activate the environment before running the command.

pip (Windows PowerShell)

pip install --upgrade glaip-sdk

Run inside an elevated PowerShell session if your organisation restricts installs. Use py -m pip install --upgrade glaip-sdk when pip is not on PATH.

Poetry (project managed)

poetry add glaip-sdk
poetry run aip --version

Ideal when the SDK ships with your application code. poetry run ensures the CLI uses the project virtual environment.

uv tool

uv tool install glaip-sdk

Great for users who prefer reproducible global installs while keeping Python projects isolated.

pipx (CLI only)

pipx install glaip-sdk
pipx ensurepath

Deploys the CLI in an isolated environment and keeps your global Python clean. Ideal for operations or QA stations. Recommended for data developers who only need the CLI.

• --upgrade (or the equivalent) ensures you pick up the latest release or refresh an existing installation.

• Using a virtual environment? Activate it first, then run the same command.

• Verify the CLI once installed:

aip --version

If pip is not available as a command, fall back to python3 -m pip (Linux/ macOS) or py -m pip (Windows). After installing, ensure ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Python311\Scripts (Windows) is on your PATH so aip resolves.

Configure Access Options

Choose the option that matches your workflow. Each method sets the same API URL and API key; you only need one of them.

.env file (project scoped)

1

Create the file

Create a .env file alongside your project code:

AIP_API_URL=https://your-aip-instance.com
AIP_API_KEY=your-api-key-here

2

Load the file

Load it with python-dotenv, your framework of choice, or a task runner.

3

When to use

Ideal when you check environment files into a secure secrets store per project.

Shell profile (persistent)

Use when you want the SDK and CLI available in every terminal.

• Linux / macOS:

  export AIP_API_URL="https://your-aip-instance.com"
  export AIP_API_KEY="your-api-key-here"

  Add the lines to ~/.bashrc, ~/.zshrc, or your shell profile to persist them.

• Windows PowerShell:

  setx AIP_API_URL "https://your-aip-instance.com"
  setx AIP_API_KEY "your-api-key-here"

  Restart the terminal after running setx so the variables are picked up.

Interactive CLI (per machine)

Run the built-in helper to store credentials in the CLI config file:

aip configure

You will be prompted for:

• API URL

• API Key

This is convenient on developer laptops or CI agents that already store the values securely.

Configuration precedence: CLI config (aip configure) > shell environment variables > .env file > library defaults.

CLI configuration is stored in ~/.aip/config.yaml (Linux/macOS) or %USERPROFILE%\\.aip\\config.yaml (Windows).

Verify Installation

Confirm both the CLI and SDK can reach your AIP instance.

CLI

aip status

Expected output includes ✅ Connected to AIP Platform.

aip status may also report:

Indicator	Meaning	Common fix
⚠️ Partial Connection	DNS/SSL failure or blocked outbound request after the client connects.	Check VPN/proxy settings, verify AIP_API_URL, and retry from a network with internet access.
❌ Connection failed	Credentials missing or rejected before any data flows.	Re-run aip configure or export AIP_API_KEY/AIP_API_URL, then rerun the command.
Timed out	CLI could not reach the API within the configured timeout.	Confirm the service is up and adjust --timeout if your environment requires longer waits.

If the error mentions Temporary failure in name resolution, your DNS cannot resolve the host—double-check the URL or try again once network connectivity is restored.

Python SDK

Security Best Practices

These apply to anyone handling API keys for the platform—whether you are a developer, DevOps engineer, or administrator.

• Use different API keys per environment (development, staging, production).

• Never commit keys to source control—prefer secret managers or CI variables.

• Rotate keys regularly and revoke unused ones promptly.

Optional CLI Configuration Helpers

Use these after installation when you need to inspect or adjust saved values.

# List current configuration
aip config list

# Get a specific value
aip config get api_url

# Update a value
aip config set api_url "https://your-aip-instance.com"

# Remove a value
aip config unset api_url

# Reset back to defaults
aip config reset

Continue

Ready to run your first agent? Head to the Quick Start and follow the Python or CLI track.