Shitty home cloud
3946ea6a — Louis Solofrizzo 3 days ago
csc, api: Add csc instance show command
8f54cb40 — Louis Solofrizzo 9 days ago
deploy: Don't restart lxd on deployment
8950b033 — Louis Solofrizzo 14 days ago
api: Enable vms, and asynchronous listing


browse log
release notes




XKCD - The Cloud

Home cloud - LouiFox instance

Table of Contents

About the Project

cisco is an effort to add a more cloud-oriented API over a LXD Cluster. The main features are what you'll expect in any major cloud provider: Tokens, Quotas, Regions, Different instance types, etc. It is mainly made for homelabs, please don't use this in production anywhere.

Getting started


  • You'll need to have an LXD cluster, with working network configuration
  • IPv6 on your cluster
  • Some servers!



In order to compile the stack, you will need:

  • golang>=1.11
  • cmake

Clone the repository:

git clone

cd and create the build directory:

cd cisco && mkdir -p build && cd build && cmake ..

Compile everything:



LXD Cluster



csc is the command-line tool used for sending orders to the cluster by your endpoint. This is some examples of this command, like default configuration files and how to manage your instances.

Config File

you can find it at ~/.config/csc/config.yml

debug: false

endpoint: Your endpoint URL, it is given to you by your cluster's admin

  • key : A unique ID, it's your token, it is print to you when you generate a token, don't loose it
  • secret : your secret exchange key, couple with you key to identify you, same as the key, it is print to you when you generate a token, don't lost it too.

Claiming an invitation

You can find the link and command in the invitation mail sent to you by your cluster's admin

The API gonna ask you your Username and a Password, don't forget them


-> % csc invite claim d04b98f48e8f8bcc15c6ae5ac050801cd6dcfd428fb5f9e65c4e16e7807340fa --endpoint
Choose an username: example
Enter a password:
Please confirm password:

Account created, getting your credentials for the configuration...
All done! You can now query the service. You should take a look at 'csc help' for more information

Send an invite

You can invite someone to join the cluster, be cool, ask your cluster admin before.

Use the command: csc invite new


-> % csc invite new
Done! User should have received an invite mail

The cluster endpoint is gonna send the same mail that you received.

Manipulating Tokens

Token is the key of cisco, we recommend you to create a unique token by machine, in case one of your machine is compromised, you can just revoke the associated token. First thing we recommend after claiming your invite is the creation of your first token.

List your tokens

You can list your tokens with: csc token list


-> % csc token list
|                 KEY                  |          DESCRIPTION           |          CREATED AT          |
| ba21f1ee-9043-8632-dd32-2cf6f52083de | Default keys (Created by the   | Fri Feb  7 13:23:57 UTC 2020 |
|                                      | command line tool)             |                              |

As you can see, when you claim your invite, csc just fill your config file with an initial default token.

Create a Token To create a token, use the command

csc token new

It will ask your Username and Password and give to you a Key and Secret to refer in your config file.


-> % csc token new
Username: example
Description (can be empty): MyMainLaptop
===== TOKEN =====
key: 64a73aca-6da0-32cf-9734-5ebdaa2bcef9
secret: XXXXXX
This is the only time you will see this secret. Do not loose it!

Uou can now verify that you have 2 token with a csc token list

Don't forget to update your config file with this value to use this token.

Revoke a Token

Simply execute :

csc token revoke <key>

Verify it is now removed with a csc token list

Managing SSH Keys

List your SSH Keys Use the command : csc ssh list

List your actual loaded keys, notice that all your keys in this list will be added to the authorized_keys when you create / reboot an instance.

Example :

-> % csc ssh list

Adding a SSH Key Use the command : csc ssh add <>

Example :

-> % csc ssh add .ssh/

Verify that the key is present with a csc ssh list

Example of a correct add:

-> % csc ssh list
|                   FINGERPRINT                   |          CREATED AT          |
| e3:de:b1:a2:32:8f:ce:10:41:2a:05:c7:42:42:42:42 | Fri Feb  7 13:55:26 UTC 2020 |

Delete a SSH Key Use the command : csc ssh delete <FINGERPRINT>

Example :

-> % csc ssh delete e3:de:b1:a2:32:8f:ce:10:41:2a:05:c7:42:42:42:42

Verify it is not present on the list with a csc ssh list

Managing Instance

List your instances Use the command : csc instance list

Example :

-> % csc instance list

Creating an Instance To create an instance, you will need 4 things:

  1. a Name
  2. an OS
  3. a Type
  4. a Size (disk)

Please be explicit and cautious with your instance's name. To choose an OS, refer to csc:image-list For the Type, refer to csc:instance-type For the Size, check your quota (csc:quota) if your need more quota, ask to your cluster's admin

Example of creation:

-> % csc instance new tototest-mybouncer debian/buster I-0 --size 30

This will create an instance with this specification :

  1. Name : tototest-mybouncer
  2. OS : Debian Buster
  3. Type : I-0 csc:instance-type
  4. Size : 30GB Verify the correct creation with a csc instance list


-> % csc instance list
|        NAME        | STATUS  | TYPE |      OS       | IPV6 | SIZE |
| tototest-mybouncer | Stopped | I-0  | debian/buster |      | 30GB |

Start an Instance Use the command : csc instance start <NAME> Example:

-> % csc instance start tototest-mybouncer

You can now see you instance is on running status and have an IPv6 address with a csc instance list Example:

-> % csc instance list
|        NAME        | STATUS  | TYPE |      OS       |                IPV6                | SIZE |
| tototest-mybouncer | Running | I-0  | debian/buster | 2001:470:c85d:32:216:3eff:fe7f:33d | 30GB |

Connecting to your instance Just a classic ssh root@<IPv6> please be sure you have your key loaded in your ssh-agent.

Stop an instance Use the command : csc instance stop <NAME> Example:

-> % csc instance stop tototest-mybouncer

Verify its state with a csc instance list

Delete an instance Use command : csc instance delete <NAME> Example:

-> % csc instance delete tototest-mybouncer

Verify the instance had been delete with a csc instance list

Be careful, this is permanent

Renaming an instance Use the command : csc instance set name Example:

-> % csc instance set name tototest-mybouncer tototest-mybouncer-renamed

Verify the new name with a csc instance list

Change the Type of an instance You can Hot-Change the type of an instance, if you need more RAM of CPU Use the command : csc instance set type <NAME> <NEW_TYPE> Example:

-> % csc instance set type tototest-mybouncer I-2

Verify with a csc instance list

Refer to csc:instance-type for all types.

Resize an instance

Use the command : csc instance set size <NAME> <NEW_SIZE> Example:

-> % csc instance set size tototest-mybouncer 50

Done! You need to restart the instance in order to use the new disk space. Verify it with a csc instance list

Tricks Command

There is two command who are compact utilization, when your are comfortable with csc you can using it.

They are : csc instance launch Description : it combine a csc instance new and a csc instance start, it creates AND start a newly instance Example:

-> % csc instance launch tototest-mybouncer debian/buster I-0 --size 30

The other one is csc instance destroy be careful with it, its a csc instance stop and csc instance delete, so you will delete your instance. Example:

-> % csc instance destroy tototest-mybouncer
Instance Types

This is an actual list of all type of instance, you can find it with csc instance types

| I-0  | x86_64       |   1 | 256MB   | container |
| I-1  | x86_64       |   2 | 2048MB  | container |
| I-2  | x86_64       |   4 | 8192MB  | container |
| I-3  | x86_64       |   8 | 16384MB | container |
| I-4  | x86_64       |  16 | 32768MB | container |
| A-0  | arm          |   1 | 256MB   | container |
| A-1  | arm          |   2 | 1024MB  | container |
Image/OS List

This is the actual list of all Image / OS available, you can find it with csc image list

|       NAME        | ARCHITECTURE |
| debian/stretch    | x86_64       |
| archlinux/current | x86_64       |
| debian/buster     | x86_64       |
| archlinux/current | armv7l       |
| debian/buster     | armv7l       |

Don't panic, csc will autodetect the architecture, its depend on your instance's type


If you want to contribute, please send your patches to ~louis/ You can look at if you need to setup your mail client.

Bug Report

Please report your bugs at todo/~louis/cisco You can also send an email to ~louis/